@wopr-network/platform-core 1.13.3 → 1.14.0

package/dist/monetization/affiliate/credit-match.test.js

@@ -1,4 +1,4 @@
-import { Credit, CreditLedger } from "@wopr-network/platform-core/credits";
+import { Credit, DrizzleLedger } from "@wopr-network/platform-core/credits";
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
 import { DrizzleAffiliateFraudRepository } from "./affiliate-fraud-repository.js";
@@ -18,12 +18,17 @@ describe("processAffiliateCreditMatch", () => {
     });
     beforeEach(async () => {
         await truncateAllTables(pool);
-        ledger = new CreditLedger(db);
+        ledger = new DrizzleLedger(db);
+        await ledger.seedSystemAccounts();
         affiliateRepo = new DrizzleAffiliateRepository(db);
         fraudRepo = new DrizzleAffiliateFraudRepository(db);
     });
     it("does nothing when tenant has no referral", async () => {
-        await ledger.credit("buyer", Credit.fromCents(1000), "purchase", "first buy", "session-1", "stripe");
+        await ledger.credit("buyer", Credit.fromCents(1000), "purchase", {
+            description: "first buy",
+            referenceId: "session-1",
+            fundingSource: "stripe",
+        });
         const result = await processAffiliateCreditMatch({
             tenantId: "buyer",
             purchaseAmount: Credit.fromCents(1000),
@@ -34,8 +39,16 @@ describe("processAffiliateCreditMatch", () => {
     });
     it("does nothing when tenant already has prior purchases", async () => {
         await affiliateRepo.recordReferral("referrer", "buyer", "abc123");
-        await ledger.credit("buyer", Credit.fromCents(500), "purchase", "old buy", "session-0", "stripe");
-        await ledger.credit("buyer", Credit.fromCents(1000), "purchase", "new buy", "session-1", "stripe");
+        await ledger.credit("buyer", Credit.fromCents(500), "purchase", {
+            description: "old buy",
+            referenceId: "session-0",
+            fundingSource: "stripe",
+        });
+        await ledger.credit("buyer", Credit.fromCents(1000), "purchase", {
+            description: "new buy",
+            referenceId: "session-1",
+            fundingSource: "stripe",
+        });
         const result = await processAffiliateCreditMatch({
             tenantId: "buyer",
             purchaseAmount: Credit.fromCents(1000),
@@ -46,7 +59,11 @@ describe("processAffiliateCreditMatch", () => {
     });
     it("credits referrer on first purchase with 100% match", async () => {
         await affiliateRepo.recordReferral("referrer", "buyer", "abc123");
-        await ledger.credit("buyer", Credit.fromCents(2000), "purchase", "first buy", "session-1", "stripe");
+        await ledger.credit("buyer", Credit.fromCents(2000), "purchase", {
+            description: "first buy",
+            referenceId: "session-1",
+            fundingSource: "stripe",
+        });
         const result = await processAffiliateCreditMatch({
             tenantId: "buyer",
             purchaseAmount: Credit.fromCents(2000),
@@ -65,7 +82,11 @@ describe("processAffiliateCreditMatch", () => {
     });
     it("respects custom match rate", async () => {
         await affiliateRepo.recordReferral("referrer", "buyer", "abc123");
-        await ledger.credit("buyer", Credit.fromCents(2000), "purchase", "first buy", "session-1", "stripe");
+        await ledger.credit("buyer", Credit.fromCents(2000), "purchase", {
+            description: "first buy",
+            referenceId: "session-1",
+            fundingSource: "stripe",
+        });
         const result = await processAffiliateCreditMatch({
             tenantId: "buyer",
             purchaseAmount: Credit.fromCents(2000),
@@ -78,7 +99,11 @@ describe("processAffiliateCreditMatch", () => {
     });
     it("is idempotent — second call returns null", async () => {
         await affiliateRepo.recordReferral("referrer", "buyer", "abc123");
-        await ledger.credit("buyer", Credit.fromCents(1000), "purchase", "first buy", "session-1", "stripe");
+        await ledger.credit("buyer", Credit.fromCents(1000), "purchase", {
+            description: "first buy",
+            referenceId: "session-1",
+            fundingSource: "stripe",
+        });
         const first = await processAffiliateCreditMatch({
             tenantId: "buyer",
             purchaseAmount: Credit.fromCents(1000),
@@ -99,7 +124,11 @@ describe("processAffiliateCreditMatch", () => {
             signupIp: "1.2.3.4",
             signupEmail: "alice+ref@gmail.com",
         });
-        await ledger.credit("buyer", Credit.fromCents(2000), "purchase", "first buy", "session-1", "stripe");
+        await ledger.credit("buyer", Credit.fromCents(2000), "purchase", {
+            description: "first buy",
+            referenceId: "session-1",
+            fundingSource: "stripe",
+        });
         const result = await processAffiliateCreditMatch({
             tenantId: "buyer",
             purchaseAmount: Credit.fromCents(2000),
@@ -127,7 +156,11 @@ describe("processAffiliateCreditMatch", () => {
             }
             // New referral
             await affiliateRepo.recordReferral("referrer", "buyer", "abc123");
-            await ledger.credit("buyer", Credit.fromCents(1000), "purchase", "first buy", "session-1", "stripe");
+            await ledger.credit("buyer", Credit.fromCents(1000), "purchase", {
+                description: "first buy",
+                referenceId: "session-1",
+                fundingSource: "stripe",
+            });
             const result = await processAffiliateCreditMatch({
                 tenantId: "buyer",
                 purchaseAmount: Credit.fromCents(1000),
@@ -151,7 +184,11 @@ describe("processAffiliateCreditMatch", () => {
             }
             // New referral
             await affiliateRepo.recordReferral("referrer", "buyer", "abc123");
-            await ledger.credit("buyer", Credit.fromCents(1000), "purchase", "first buy", "session-1", "stripe");
+            await ledger.credit("buyer", Credit.fromCents(1000), "purchase", {
+                description: "first buy",
+                referenceId: "session-1",
+                fundingSource: "stripe",
+            });
             const result = await processAffiliateCreditMatch({
                 tenantId: "buyer",
                 purchaseAmount: Credit.fromCents(1000),
@@ -167,7 +204,11 @@ describe("processAffiliateCreditMatch", () => {
         });
         it("allows payout when under both caps", async () => {
             await affiliateRepo.recordReferral("referrer", "buyer", "abc123");
-            await ledger.credit("buyer", Credit.fromCents(2000), "purchase", "first buy", "session-1", "stripe");
+            await ledger.credit("buyer", Credit.fromCents(2000), "purchase", {
+                description: "first buy",
+                referenceId: "session-1",
+                fundingSource: "stripe",
+            });
             const result = await processAffiliateCreditMatch({
                 tenantId: "buyer",
                 purchaseAmount: Credit.fromCents(2000),
@@ -184,7 +225,11 @@ describe("processAffiliateCreditMatch", () => {
         await affiliateRepo.recordReferral("referrer", "buyer", "abc123", {
             signupIp: "1.2.3.4",
         });
-        await ledger.credit("buyer", Credit.fromCents(2000), "purchase", "first buy", "session-1", "stripe");
+        await ledger.credit("buyer", Credit.fromCents(2000), "purchase", {
+            description: "first buy",
+            referenceId: "session-1",
+            fundingSource: "stripe",
+        });
         const result = await processAffiliateCreditMatch({
             tenantId: "buyer",
             purchaseAmount: Credit.fromCents(2000),

package/dist/monetization/affiliate/new-user-bonus.d.ts

@@ -1,10 +1,10 @@
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import { Credit } from "@wopr-network/platform-core/credits";
 import type { IAffiliateRepository } from "./drizzle-affiliate-repository.js";
 /** Default bonus rate: 20% of purchase amount. Override with AFFILIATE_NEW_USER_BONUS_RATE env var. */
 export declare const DEFAULT_BONUS_RATE: number;
 export interface NewUserBonusParams {
-    ledger: ICreditLedger;
+    ledger: ILedger;
     affiliateRepo: IAffiliateRepository;
     referredTenantId: string;
     purchaseAmount: Credit;

package/dist/monetization/affiliate/new-user-bonus.js

@@ -34,6 +34,9 @@ export async function grantNewUserBonus(params) {
     // 5. Mark first purchase on the referral row (no-op if already set)
     await affiliateRepo.markFirstPurchase(referredTenantId);
     // 6. Credit the bonus
-    await ledger.credit(referredTenantId, bonus, "affiliate_bonus", `New user first-purchase bonus (${Math.round(rate * 100)}%)`, refId);
+    await ledger.credit(referredTenantId, bonus, "affiliate_bonus", {
+        description: `New user first-purchase bonus (${Math.round(rate * 100)}%)`,
+        referenceId: refId,
+    });
     return { granted: true, bonus };
 }

package/dist/monetization/affiliate/new-user-bonus.test.js

@@ -1,4 +1,4 @@
-import { Credit, CreditLedger } from "@wopr-network/platform-core/credits";
+import { Credit, DrizzleLedger } from "@wopr-network/platform-core/credits";
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
 import { DrizzleAffiliateRepository } from "./drizzle-affiliate-repository.js";
@@ -16,7 +16,8 @@ describe("grantNewUserBonus", () => {
     });
     beforeEach(async () => {
         await truncateAllTables(pool);
-        ledger = new CreditLedger(db);
+        ledger = new DrizzleLedger(db);
+        await ledger.seedSystemAccounts();
         affiliateRepo = new DrizzleAffiliateRepository(db);
     });
     it("DEFAULT_BONUS_RATE equals 0.20", () => {
@@ -37,7 +38,7 @@ describe("grantNewUserBonus", () => {
         expect((await ledger.balance("referred-1")).toCents()).toBe(1000);
         const txns = await ledger.history("referred-1");
         expect(txns).toHaveLength(1);
-        expect(txns[0].type).toBe("affiliate_bonus");
+        expect(txns[0].entryType).toBe("affiliate_bonus");
         expect(txns[0].referenceId).toBe("affiliate-bonus:referred-1");
         expect(txns[0].description).toContain("first-purchase bonus");
     });

package/dist/monetization/credits/auto-topup-charge.d.ts

@@ -1,5 +1,5 @@
 import type { ITenantCustomerRepository } from "@wopr-network/platform-core/billing";
-import type { Credit, ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { Credit, ILedger } from "@wopr-network/platform-core/credits";
 import Stripe from "stripe";
 import type { IAutoTopupEventLogRepository } from "./auto-topup-event-log-repository.js";
 /** After this many consecutive Stripe failures, the auto-topup mode is disabled. */
@@ -7,7 +7,7 @@ export declare const MAX_CONSECUTIVE_FAILURES = 3;
 export interface AutoTopupChargeDeps {
     stripe: Stripe;
     tenantRepo: ITenantCustomerRepository;
-    creditLedger: ICreditLedger;
+    creditLedger: ILedger;
     eventLogRepo: IAutoTopupEventLogRepository;
 }
 export interface AutoTopupChargeResult {

package/dist/monetization/credits/auto-topup-charge.js

@@ -113,7 +113,11 @@ export async function chargeAutoTopup(deps, tenantId, amount, source) {
     // 5. Credit the ledger (idempotent via referenceId = PI ID)
     try {
         if (!(await deps.creditLedger.hasReferenceId(paymentIntent.id))) {
-            await deps.creditLedger.credit(tenantId, amount, "purchase", `Auto-topup (${source})`, paymentIntent.id, "stripe");
+            await deps.creditLedger.credit(tenantId, amount, "purchase", {
+                description: `Auto-topup (${source})`,
+                referenceId: paymentIntent.id,
+                fundingSource: "stripe",
+            });
         }
     }
     catch (err) {

package/dist/monetization/credits/auto-topup-charge.test.js

@@ -1,5 +1,5 @@
 import crypto from "node:crypto";
-import { Credit, CreditLedger } from "@wopr-network/platform-core/credits";
+import { Credit, DrizzleLedger } from "@wopr-network/platform-core/credits";
 import Stripe from "stripe";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { creditAutoTopup } from "../../db/schema/credit-auto-topup.js";
@@ -46,7 +46,8 @@ describe("chargeAutoTopup", () => {
     });
     beforeEach(async () => {
         await truncateAllTables(pool);
-        ledger = new CreditLedger(db);
+        ledger = new DrizzleLedger(db);
+        await ledger.seedSystemAccounts();
     });
     it("charges Stripe and credits ledger on success", async () => {
         const stripe = mockStripe();
@@ -62,8 +63,8 @@ describe("chargeAutoTopup", () => {
         expect(result.paymentReference).toEqual(expect.any(String));
         expect((await ledger.balance("t1")).toCents()).toBe(500);
         const history = await ledger.history("t1");
-        expect(history[0].type).toBe("purchase");
-        expect(history[0].fundingSource).toBe("stripe");
+        expect(history[0].entryType).toBe("purchase");
+        expect(history[0].metadata?.fundingSource).toBe("stripe");
     });
     it("writes success event to credit_auto_topup log", async () => {
         const stripe = mockStripe();

package/dist/monetization/credits/auto-topup-usage.d.ts

@@ -1,8 +1,8 @@
-import type { Credit, IAutoTopupSettingsRepository, ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { Credit, IAutoTopupSettingsRepository, ILedger } from "@wopr-network/platform-core/credits";
 import type { AutoTopupChargeResult } from "./auto-topup-charge.js";
 export interface UsageTopupDeps {
     settingsRepo: IAutoTopupSettingsRepository;
-    creditLedger: ICreditLedger;
+    creditLedger: ILedger;
     /** Injected charge function (allows mocking in tests). */
     chargeAutoTopup: (tenantId: string, amount: Credit, source: string) => Promise<AutoTopupChargeResult>;
     /** Optional tenant status check. If provided and returns non-null, skip the charge. */

package/dist/monetization/credits/auto-topup-usage.test.js

@@ -1,4 +1,4 @@
-import { Credit, CreditLedger, DrizzleAutoTopupSettingsRepository } from "@wopr-network/platform-core/credits";
+import { Credit, DrizzleAutoTopupSettingsRepository, DrizzleLedger } from "@wopr-network/platform-core/credits";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
 import { maybeTriggerUsageTopup } from "./auto-topup-usage.js";
@@ -15,7 +15,8 @@ describe("maybeTriggerUsageTopup", () => {
     });
     beforeEach(async () => {
         await truncateAllTables(pool);
-        ledger = new CreditLedger(db);
+        ledger = new DrizzleLedger(db);
+        await ledger.seedSystemAccounts();
         settingsRepo = new DrizzleAutoTopupSettingsRepository(db);
     });
     it("does nothing when tenant has no auto-topup settings", async () => {
@@ -26,7 +27,11 @@ describe("maybeTriggerUsageTopup", () => {
     });
     it("does nothing when usage_enabled is false", async () => {
         await settingsRepo.upsert("t1", { usageEnabled: false });
-        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+            description: "buy",
+            referenceId: "ref-1",
+            fundingSource: "stripe",
+        });
         const mockCharge = vi.fn();
         const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -38,7 +43,11 @@ describe("maybeTriggerUsageTopup", () => {
             usageThreshold: Credit.fromCents(100),
             usageTopup: Credit.fromCents(500),
         });
-        await ledger.credit("t1", Credit.fromCents(200), "purchase", "buy", "ref-1", "stripe");
+        await ledger.credit("t1", Credit.fromCents(200), "purchase", {
+            description: "buy",
+            referenceId: "ref-1",
+            fundingSource: "stripe",
+        });
         const mockCharge = vi.fn();
         const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -50,7 +59,11 @@ describe("maybeTriggerUsageTopup", () => {
             usageThreshold: Credit.fromCents(100),
             usageTopup: Credit.fromCents(500),
         });
-        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+            description: "buy",
+            referenceId: "ref-1",
+            fundingSource: "stripe",
+        });
         const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_123" });
         const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -59,7 +72,11 @@ describe("maybeTriggerUsageTopup", () => {
     it("skips when charge is already in-flight", async () => {
         await settingsRepo.upsert("t1", { usageEnabled: true, usageThreshold: Credit.fromCents(100) });
         await settingsRepo.setUsageChargeInFlight("t1", true);
-        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+            description: "buy",
+            referenceId: "ref-1",
+            fundingSource: "stripe",
+        });
         const mockCharge = vi.fn();
         const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -72,7 +89,11 @@ describe("maybeTriggerUsageTopup", () => {
             usageThreshold: Credit.fromCents(500),
             usageTopup: Credit.fromCents(2000),
         });
-        await ledger.credit("t1", Credit.fromCents(100), "purchase", "buy", "ref-1", "stripe");
+        await ledger.credit("t1", Credit.fromCents(100), "purchase", {
+            description: "buy",
+            referenceId: "ref-1",
+            fundingSource: "stripe",
+        });
         const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_race" });
         const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         // Fire two concurrent calls — both see balance < threshold,
@@ -91,7 +112,11 @@ describe("maybeTriggerUsageTopup", () => {
             usageThreshold: Credit.fromCents(100),
             usageTopup: Credit.fromCents(500),
         });
-        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+            description: "buy",
+            referenceId: "ref-1",
+            fundingSource: "stripe",
+        });
         const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_123" });
         const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         // First call — triggers charge, flag set then cleared
@@ -109,7 +134,11 @@ describe("maybeTriggerUsageTopup", () => {
             usageThreshold: Credit.fromCents(100),
             usageTopup: Credit.fromCents(500),
         });
-        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+            description: "buy",
+            referenceId: "ref-1",
+            fundingSource: "stripe",
+        });
         const mockCharge = vi
             .fn()
             .mockRejectedValueOnce(new Error("Stripe network error"))
@@ -132,7 +161,11 @@ describe("maybeTriggerUsageTopup", () => {
         });
         await settingsRepo.incrementUsageFailures("t1");
         await settingsRepo.incrementUsageFailures("t1");
-        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+            description: "buy",
+            referenceId: "ref-1",
+            fundingSource: "stripe",
+        });
         const mockCharge = vi.fn().mockResolvedValue({ success: true });
         const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -144,7 +177,11 @@ describe("maybeTriggerUsageTopup", () => {
             usageThreshold: Credit.fromCents(100),
             usageTopup: Credit.fromCents(500),
         });
-        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+            description: "buy",
+            referenceId: "ref-1",
+            fundingSource: "stripe",
+        });
         const mockCharge = vi.fn().mockResolvedValue({ success: false, error: "declined" });
         const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");
@@ -170,7 +207,11 @@ describe("maybeTriggerUsageTopup", () => {
         });
         await settingsRepo.incrementUsageFailures("t1");
         await settingsRepo.incrementUsageFailures("t1");
-        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", {
+            description: "buy",
+            referenceId: "ref-1",
+            fundingSource: "stripe",
+        });
         const mockCharge = vi.fn().mockResolvedValue({ success: false, error: "declined" });
         const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
         await maybeTriggerUsageTopup(deps, "t1");

package/dist/monetization/credits/bot-billing.d.ts

@@ -1,4 +1,4 @@
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import { Credit } from "@wopr-network/platform-core/credits";
 import type { IBotInstanceRepository } from "../../fleet/bot-instance-repository.js";
 import type { INodeCommandBus } from "../../fleet/node-command-bus.js";
@@ -11,7 +11,7 @@ export interface IBotBilling {
     suspendBot(botId: string): Promise<void>;
     suspendAllForTenant(tenantId: string): Promise<string[]>;
     reactivateBot(botId: string): Promise<void>;
-    checkReactivation(tenantId: string, ledger: ICreditLedger): Promise<string[]>;
+    checkReactivation(tenantId: string, ledger: ILedger): Promise<string[]>;
     destroyBot(botId: string): Promise<void>;
     destroyExpiredBots(): Promise<string[]>;
     getBotBilling(botId: string): Promise<unknown>;
@@ -56,7 +56,7 @@ export declare class DrizzleBotBilling implements IBotBilling {
      *
      * @returns IDs of reactivated bots.
      */
-    checkReactivation(tenantId: string, ledger: ICreditLedger): Promise<string[]>;
+    checkReactivation(tenantId: string, ledger: ILedger): Promise<string[]>;
     /**
      * Mark a bot as destroyed.
      * Sets billingState='destroyed'. Actual Docker cleanup is handled by the caller.

package/dist/monetization/credits/bot-billing.test.js

@@ -1,4 +1,4 @@
-import { Credit, CreditLedger } from "@wopr-network/platform-core/credits";
+import { Credit, DrizzleLedger } from "@wopr-network/platform-core/credits";
 import { sql } from "drizzle-orm";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { botInstances } from "../../db/schema/bot-instances.js";
@@ -61,7 +61,8 @@ describe("BotBilling", () => {
     beforeEach(async () => {
         await truncateAllTables(pool);
         billing = new BotBilling(new DrizzleBotInstanceRepository(db));
-        ledger = new CreditLedger(db);
+        ledger = new DrizzleLedger(db);
+        await ledger.seedSystemAccounts();
     });
     describe("registerBot", () => {
         it("registers a bot in active billing state", async () => {
@@ -178,7 +179,11 @@ describe("BotBilling", () => {
             await billing.registerBot("bot-2", "tenant-1", "bot-b");
             await billing.suspendBot("bot-1");
             await billing.suspendBot("bot-2");
-            await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "test credit", "ref-1", "stripe");
+            await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", {
+                description: "test credit",
+                referenceId: "ref-1",
+                fundingSource: "stripe",
+            });
             const reactivated = await billing.checkReactivation("tenant-1", ledger);
             expect(reactivated.sort()).toEqual(["bot-1", "bot-2"]);
             expect(await billing.getActiveBotCount("tenant-1")).toBe(2);
@@ -193,12 +198,20 @@ describe("BotBilling", () => {
         it("does not reactivate destroyed bots", async () => {
             await billing.registerBot("bot-1", "tenant-1", "bot-a");
             await billing.destroyBot("bot-1");
-            await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "test credit", "ref-1", "stripe");
+            await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", {
+                description: "test credit",
+                referenceId: "ref-1",
+                fundingSource: "stripe",
+            });
             const reactivated = await billing.checkReactivation("tenant-1", ledger);
             expect(reactivated).toEqual([]);
         });
         it("returns empty array for tenant with no bots", async () => {
-            await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "test credit", "ref-1", "stripe");
+            await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", {
+                description: "test credit",
+                referenceId: "ref-1",
+                fundingSource: "stripe",
+            });
             const reactivated = await billing.checkReactivation("tenant-1", ledger);
             expect(reactivated).toEqual([]);
         });

package/dist/monetization/credits/credit-expiry-cron.test.js

@@ -1,4 +1,4 @@
-import { Credit, DrizzleCreditLedger, runCreditExpiryCron } from "@wopr-network/platform-core/credits";
+import { Credit, DrizzleLedger, runCreditExpiryCron } from "@wopr-network/platform-core/credits";
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { createTestDb, truncateAllTables } from "../../test/db.js";
 describe("runCreditExpiryCron", () => {
@@ -7,13 +7,14 @@ describe("runCreditExpiryCron", () => {
     beforeAll(async () => {
         const { db, pool: p } = await createTestDb();
         pool = p;
-        ledger = new DrizzleCreditLedger(db);
+        ledger = new DrizzleLedger(db);
     });
     afterAll(async () => {
         await pool.close();
     });
     beforeEach(async () => {
         await truncateAllTables(pool);
+        await ledger.seedSystemAccounts();
     });
     // All tests pass an explicit `now` parameter — hardcoded dates are time-independent
     // because runCreditExpiryCron never reads the system clock.
@@ -24,7 +25,11 @@ describe("runCreditExpiryCron", () => {
         expect(result.errors).toEqual([]);
     });
     it("debits expired promotional credit grant", async () => {
-        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", "New user bonus", "promo:tenant-1", undefined, undefined, "2026-01-10T00:00:00Z");
+        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+            description: "New user bonus",
+            referenceId: "promo:tenant-1",
+            expiresAt: "2026-01-10T00:00:00Z",
+        });
         const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
         expect(result.processed).toBe(1);
         expect(result.expired).toContain("tenant-1");
@@ -32,29 +37,41 @@ describe("runCreditExpiryCron", () => {
         expect(balance.toCents()).toBe(0);
     });
     it("does not debit non-expired credits", async () => {
-        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", "Future bonus", "promo:tenant-1-future", undefined, undefined, "2026-02-01T00:00:00Z");
+        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+            description: "Future bonus",
+            referenceId: "promo:tenant-1-future",
+            expiresAt: "2026-02-01T00:00:00Z",
+        });
         const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
         expect(result.processed).toBe(0);
         const balance = await ledger.balance("tenant-1");
         expect(balance.toCents()).toBe(500);
     });
     it("does not debit credits without expires_at", async () => {
-        await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "Top-up");
+        await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", { description: "Top-up" });
         const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
         expect(result.processed).toBe(0);
         const balance = await ledger.balance("tenant-1");
         expect(balance.toCents()).toBe(500);
     });
     it("only debits up to available balance when partially consumed", async () => {
-        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", "Promo", "promo:partial", undefined, undefined, "2026-01-10T00:00:00Z");
-        await ledger.debit("tenant-1", Credit.fromCents(300), "bot_runtime", "Runtime");
+        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+            description: "Promo",
+            referenceId: "promo:partial",
+            expiresAt: "2026-01-10T00:00:00Z",
+        });
+        await ledger.debit("tenant-1", Credit.fromCents(300), "bot_runtime", { description: "Runtime" });
         const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
         expect(result.processed).toBe(1);
         const balance = await ledger.balance("tenant-1");
         expect(balance.toCents()).toBe(0);
     });
     it("is idempotent -- does not double-debit on second run", async () => {
-        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", "Promo", "promo:idemp", undefined, undefined, "2026-01-10T00:00:00Z");
+        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+            description: "Promo",
+            referenceId: "promo:idemp",
+            expiresAt: "2026-01-10T00:00:00Z",
+        });
         await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
         const balanceAfterFirst = await ledger.balance("tenant-1");
         const result2 = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });

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

@@ -1,9 +1,7 @@
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import { Credit } from "@wopr-network/platform-core/credits";
-import type { ICreditTransactionRepository } from "./credit-transaction-repository.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. */

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

@@ -21,7 +21,7 @@ export async function runDividendCron(cfg) {
     // 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;
         logger.info("Dividend cron already ran for this date", { targetDate: cfg.targetDate });
@@ -30,14 +30,14 @@ export async function runDividendCron(cfg) {
     // 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);
+    const dailyPurchaseTotalCredit = await cfg.ledger.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);
+    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) {
@@ -61,7 +61,10 @@ export async function runDividendCron(cfg) {
     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) {