@wopr-network/platform-core 1.39.1 → 1.39.3

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

@@ -81,4 +81,29 @@ describe("runCreditExpiryCron", () => {
         const balanceAfterSecond = await ledger.balance("tenant-1");
         expect(balanceAfterSecond.toCents()).toBe(balanceAfterFirst.toCents());
     });
+    it("does not return unknown entry type even with expiresAt metadata", async () => {
+        // Simulate a hypothetical new entry type that has expiresAt in metadata.
+        // With the old denylist approach, this would be incorrectly returned.
+        // With the allowlist, it must be excluded.
+        const entry = await ledger.post({
+            entryType: "marketplace_fee",
+            tenantId: "tenant-1",
+            description: "Hypothetical new debit type with expiresAt",
+            metadata: { expiresAt: "2026-01-10T00:00:00Z" },
+            lines: [
+                { accountCode: "2000:tenant-1", amount: Credit.fromCents(100), side: "debit" },
+                { accountCode: "4000", amount: Credit.fromCents(100), side: "credit" },
+            ],
+        });
+        // Give tenant a balance first so it's not filtered by zero-balance
+        await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", {
+            description: "Top-up",
+        });
+        const expired = await ledger.expiredCredits("2026-01-15T00:00:00Z");
+        const ids = expired.map((e) => e.entryId);
+        expect(ids).not.toContain(entry.id);
+        // Full cron should also not touch it
+        const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        expect(result.processed).toBe(0);
+    });
 });

package/dist/credits/credit.js

@@ -91,15 +91,27 @@ export class Credit {
     }
     /** Add another Credit, returning a new Credit. */
     add(other) {
-        return new Credit(this.raw + other.raw);
+        const result = this.raw + other.raw;
+        if (!Number.isSafeInteger(result)) {
+            throw new RangeError(`Credit.add overflow: ${this.raw} + ${other.raw} = ${result}`);
+        }
+        return new Credit(result);
     }
     /** Subtract another Credit, returning a new Credit (may be negative). */
     subtract(other) {
-        return new Credit(this.raw - other.raw);
+        const result = this.raw - other.raw;
+        if (!Number.isSafeInteger(result)) {
+            throw new RangeError(`Credit.subtract overflow: ${this.raw} - ${other.raw} = ${result}`);
+        }
+        return new Credit(result);
     }
     /** Multiply by a factor, rounding to nearest raw unit. */
     multiply(factor) {
-        return new Credit(Math.round(this.raw * factor));
+        const result = Math.round(this.raw * factor);
+        if (!Number.isSafeInteger(result)) {
+            throw new RangeError(`Credit.multiply overflow: ${this.raw} * ${factor} = ${result}`);
+        }
+        return new Credit(result);
     }
     /** True if this credit is negative. */
     isNegative() {

package/dist/credits/credit.test.js

@@ -103,6 +103,38 @@ describe("Credit", () => {
         it("multiply by zero gives zero", () => {
             expect(Credit.fromDollars(5).multiply(0).isZero()).toBe(true);
         });
+        it("add throws RangeError on positive overflow", () => {
+            const a = Credit.fromRaw(Number.MAX_SAFE_INTEGER);
+            const b = Credit.fromRaw(1);
+            expect(() => a.add(b)).toThrow(RangeError);
+        });
+        it("subtract throws RangeError on negative overflow", () => {
+            const a = Credit.fromRaw(-Number.MAX_SAFE_INTEGER);
+            const b = Credit.fromRaw(1);
+            expect(() => a.subtract(b)).toThrow(RangeError);
+        });
+        it("multiply throws RangeError on overflow", () => {
+            const a = Credit.fromRaw(Number.MAX_SAFE_INTEGER);
+            expect(() => a.multiply(2)).toThrow(RangeError);
+        });
+        it("multiply throws RangeError on Infinity factor", () => {
+            const a = Credit.fromRaw(1);
+            expect(() => a.multiply(Infinity)).toThrow(RangeError);
+        });
+        it("multiply throws RangeError on NaN factor", () => {
+            const a = Credit.fromRaw(1);
+            expect(() => a.multiply(NaN)).toThrow(RangeError);
+        });
+        it("add does not throw for values within safe range", () => {
+            const a = Credit.fromRaw(Number.MAX_SAFE_INTEGER - 1);
+            const b = Credit.fromRaw(1);
+            expect(a.add(b).toRaw()).toBe(Number.MAX_SAFE_INTEGER);
+        });
+        it("subtract does not throw for values within safe range", () => {
+            const a = Credit.fromRaw(-(Number.MAX_SAFE_INTEGER - 1));
+            const b = Credit.fromRaw(1);
+            expect(a.subtract(b).toRaw()).toBe(-Number.MAX_SAFE_INTEGER);
+        });
     });
     describe("comparison", () => {
         it("isNegative returns true for negative", () => {

package/dist/credits/ledger.d.ts

@@ -99,6 +99,12 @@ export interface DebitOpts {
 export declare const CREDIT_TYPE_ACCOUNT: Record<CreditType, string>;
 /** Maps debit (money-out) types to the credit-side account code. */
 export declare const DEBIT_TYPE_ACCOUNT: Record<DebitType, string>;
+/**
+ * Entry types eligible for credit expiry (allowlist).
+ * Only journal entries with these types can be returned by expiredCredits().
+ * Derived from CreditType — if you add a new CreditType, add it here too.
+ */
+export declare const EXPIRABLE_CREDIT_TYPES: readonly ["signup_grant", "admin_grant", "purchase", "bounty", "referral", "promo", "community_dividend", "affiliate_bonus", "affiliate_match", "correction"];
 export interface SystemAccount {
     code: string;
     name: string;

package/dist/credits/ledger.js

@@ -54,6 +54,23 @@ export const DEBIT_TYPE_ACCOUNT = {
     refund: "1000", // CR cash (money out)
     correction: "5070", // CR expense:correction
 };
+/**
+ * Entry types eligible for credit expiry (allowlist).
+ * Only journal entries with these types can be returned by expiredCredits().
+ * Derived from CreditType — if you add a new CreditType, add it here too.
+ */
+export const EXPIRABLE_CREDIT_TYPES = [
+    "signup_grant",
+    "admin_grant",
+    "purchase",
+    "bounty",
+    "referral",
+    "promo",
+    "community_dividend",
+    "affiliate_bonus",
+    "affiliate_match",
+    "correction",
+];
 export const SYSTEM_ACCOUNTS = [
     // Assets
     { code: "1000", name: "Cash", type: "asset", normalSide: "debit" },
@@ -479,7 +496,7 @@ export class DrizzleLedger {
 				)`,
         })
             .from(journalEntries)
-            .where(and(isNotNull(sql `${journalEntries.metadata}->>'expiresAt'`), sql `(${journalEntries.metadata}->>'expiresAt') <= ${now}`, sql `${journalEntries.entryType} NOT IN ('credit_expiry', 'bot_runtime', 'adapter_usage', 'addon', 'refund')`));
+            .where(and(isNotNull(sql `${journalEntries.metadata}->>'expiresAt'`), sql `(${journalEntries.metadata}->>'expiresAt') <= ${now}`, sql `${journalEntries.entryType} IN (${sql.join(EXPIRABLE_CREDIT_TYPES.map((t) => sql `${t}`), sql `, `)})`));
         const result = [];
         for (const row of rows) {
             if (!row.amount)

package/dist/credits/ledger.test.js

@@ -363,6 +363,61 @@ describe("DrizzleLedger", () => {
         });
     });
     // -----------------------------------------------------------------------
+    // expiredCredits()
+    // -----------------------------------------------------------------------
+    describe("expiredCredits()", () => {
+        it("returns entries with expirable types whose expiresAt has passed", async () => {
+            // Post a signup_grant (in EXPIRABLE_CREDIT_TYPES) with an expiresAt in the past
+            await ledger.credit("t1", Credit.fromCents(100), "signup_grant", {
+                expiresAt: "2020-01-01T00:00:00Z",
+            });
+            const expired = await ledger.expiredCredits(new Date().toISOString());
+            expect(expired).toHaveLength(1);
+            expect(expired[0].tenantId).toBe("t1");
+            expect(expired[0].amount.toCentsRounded()).toBe(100);
+        });
+        it("excludes entries whose type is not in EXPIRABLE_CREDIT_TYPES", async () => {
+            // Post a credit-side entry on the liability account with an unknown entry type
+            // so the liability credit line is present (the subquery finds an amount) but
+            // the allowlist filter must exclude it.
+            await ledger.post({
+                entryType: "marketplace_fee", // NOT in EXPIRABLE_CREDIT_TYPES
+                tenantId: "t1",
+                metadata: { expiresAt: "2020-01-01T00:00:00Z" },
+                lines: [
+                    { accountCode: "1000", amount: Credit.fromCents(100), side: "debit" },
+                    { accountCode: "2000:t1", amount: Credit.fromCents(100), side: "credit" },
+                ],
+            });
+            const expired = await ledger.expiredCredits(new Date().toISOString());
+            expect(expired).toHaveLength(0);
+        });
+        it("excludes entries whose expiresAt is in the future", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase", {
+                expiresAt: "2099-01-01T00:00:00Z",
+            });
+            const expired = await ledger.expiredCredits(new Date().toISOString());
+            expect(expired).toHaveLength(0);
+        });
+        it("excludes entries already clawed back (idempotency)", async () => {
+            const entry = await ledger.credit("t1", Credit.fromCents(100), "purchase", {
+                expiresAt: "2020-01-01T00:00:00Z",
+            });
+            // Simulate a prior expiry entry by posting with the expiry referenceId
+            await ledger.post({
+                entryType: "credit_expiry",
+                tenantId: "t1",
+                referenceId: `expiry:${entry.id}`,
+                lines: [
+                    { accountCode: "2000:t1", amount: Credit.fromCents(100), side: "debit" },
+                    { accountCode: "4060", amount: Credit.fromCents(100), side: "credit" },
+                ],
+            });
+            const expired = await ledger.expiredCredits(new Date().toISOString());
+            expect(expired).toHaveLength(0);
+        });
+    });
+    // -----------------------------------------------------------------------
     // memberUsage()
     // -----------------------------------------------------------------------
     describe("memberUsage()", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.39.1",
+  "version": "1.39.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/credits/credit-expiry-cron.test.ts

@@ -103,4 +103,33 @@ describe("runCreditExpiryCron", () => {
     const balanceAfterSecond = await ledger.balance("tenant-1");
     expect(balanceAfterSecond.toCents()).toBe(balanceAfterFirst.toCents());
   });
+
+  it("does not return unknown entry type even with expiresAt metadata", async () => {
+    // Simulate a hypothetical new entry type that has expiresAt in metadata.
+    // With the old denylist approach, this would be incorrectly returned.
+    // With the allowlist, it must be excluded.
+    const entry = await ledger.post({
+      entryType: "marketplace_fee",
+      tenantId: "tenant-1",
+      description: "Hypothetical new debit type with expiresAt",
+      metadata: { expiresAt: "2026-01-10T00:00:00Z" },
+      lines: [
+        { accountCode: "2000:tenant-1", amount: Credit.fromCents(100), side: "debit" },
+        { accountCode: "4000", amount: Credit.fromCents(100), side: "credit" },
+      ],
+    });
+
+    // Give tenant a balance first so it's not filtered by zero-balance
+    await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", {
+      description: "Top-up",
+    });
+
+    const expired = await ledger.expiredCredits("2026-01-15T00:00:00Z");
+    const ids = expired.map((e) => e.entryId);
+    expect(ids).not.toContain(entry.id);
+
+    // Full cron should also not touch it
+    const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+    expect(result.processed).toBe(0);
+  });
 });

package/src/credits/credit.test.ts

@@ -124,6 +124,45 @@ describe("Credit", () => {
     it("multiply by zero gives zero", () => {
       expect(Credit.fromDollars(5).multiply(0).isZero()).toBe(true);
     });
+
+    it("add throws RangeError on positive overflow", () => {
+      const a = Credit.fromRaw(Number.MAX_SAFE_INTEGER);
+      const b = Credit.fromRaw(1);
+      expect(() => a.add(b)).toThrow(RangeError);
+    });
+
+    it("subtract throws RangeError on negative overflow", () => {
+      const a = Credit.fromRaw(-Number.MAX_SAFE_INTEGER);
+      const b = Credit.fromRaw(1);
+      expect(() => a.subtract(b)).toThrow(RangeError);
+    });
+
+    it("multiply throws RangeError on overflow", () => {
+      const a = Credit.fromRaw(Number.MAX_SAFE_INTEGER);
+      expect(() => a.multiply(2)).toThrow(RangeError);
+    });
+
+    it("multiply throws RangeError on Infinity factor", () => {
+      const a = Credit.fromRaw(1);
+      expect(() => a.multiply(Infinity)).toThrow(RangeError);
+    });
+
+    it("multiply throws RangeError on NaN factor", () => {
+      const a = Credit.fromRaw(1);
+      expect(() => a.multiply(NaN)).toThrow(RangeError);
+    });
+
+    it("add does not throw for values within safe range", () => {
+      const a = Credit.fromRaw(Number.MAX_SAFE_INTEGER - 1);
+      const b = Credit.fromRaw(1);
+      expect(a.add(b).toRaw()).toBe(Number.MAX_SAFE_INTEGER);
+    });
+
+    it("subtract does not throw for values within safe range", () => {
+      const a = Credit.fromRaw(-(Number.MAX_SAFE_INTEGER - 1));
+      const b = Credit.fromRaw(1);
+      expect(a.subtract(b).toRaw()).toBe(-Number.MAX_SAFE_INTEGER);
+    });
   });
 
   describe("comparison", () => {

package/src/credits/credit.ts

@@ -101,17 +101,29 @@ export class Credit {
 
   /** Add another Credit, returning a new Credit. */
   add(other: Credit): Credit {
-    return new Credit(this.raw + other.raw);
+    const result = this.raw + other.raw;
+    if (!Number.isSafeInteger(result)) {
+      throw new RangeError(`Credit.add overflow: ${this.raw} + ${other.raw} = ${result}`);
+    }
+    return new Credit(result);
   }
 
   /** Subtract another Credit, returning a new Credit (may be negative). */
   subtract(other: Credit): Credit {
-    return new Credit(this.raw - other.raw);
+    const result = this.raw - other.raw;
+    if (!Number.isSafeInteger(result)) {
+      throw new RangeError(`Credit.subtract overflow: ${this.raw} - ${other.raw} = ${result}`);
+    }
+    return new Credit(result);
   }
 
   /** Multiply by a factor, rounding to nearest raw unit. */
   multiply(factor: number): Credit {
-    return new Credit(Math.round(this.raw * factor));
+    const result = Math.round(this.raw * factor);
+    if (!Number.isSafeInteger(result)) {
+      throw new RangeError(`Credit.multiply overflow: ${this.raw} * ${factor} = ${result}`);
+    }
+    return new Credit(result);
   }
 
   /** True if this credit is negative. */

package/src/credits/ledger.test.ts

@@ -449,6 +449,71 @@ describe("DrizzleLedger", () => {
     });
   });
 
+  // -----------------------------------------------------------------------
+  // expiredCredits()
+  // -----------------------------------------------------------------------
+
+  describe("expiredCredits()", () => {
+    it("returns entries with expirable types whose expiresAt has passed", async () => {
+      // Post a signup_grant (in EXPIRABLE_CREDIT_TYPES) with an expiresAt in the past
+      await ledger.credit("t1", Credit.fromCents(100), "signup_grant", {
+        expiresAt: "2020-01-01T00:00:00Z",
+      });
+
+      const expired = await ledger.expiredCredits(new Date().toISOString());
+      expect(expired).toHaveLength(1);
+      expect(expired[0].tenantId).toBe("t1");
+      expect(expired[0].amount.toCentsRounded()).toBe(100);
+    });
+
+    it("excludes entries whose type is not in EXPIRABLE_CREDIT_TYPES", async () => {
+      // Post a credit-side entry on the liability account with an unknown entry type
+      // so the liability credit line is present (the subquery finds an amount) but
+      // the allowlist filter must exclude it.
+      await ledger.post({
+        entryType: "marketplace_fee", // NOT in EXPIRABLE_CREDIT_TYPES
+        tenantId: "t1",
+        metadata: { expiresAt: "2020-01-01T00:00:00Z" },
+        lines: [
+          { accountCode: "1000", amount: Credit.fromCents(100), side: "debit" },
+          { accountCode: "2000:t1", amount: Credit.fromCents(100), side: "credit" },
+        ],
+      });
+
+      const expired = await ledger.expiredCredits(new Date().toISOString());
+      expect(expired).toHaveLength(0);
+    });
+
+    it("excludes entries whose expiresAt is in the future", async () => {
+      await ledger.credit("t1", Credit.fromCents(100), "purchase", {
+        expiresAt: "2099-01-01T00:00:00Z",
+      });
+
+      const expired = await ledger.expiredCredits(new Date().toISOString());
+      expect(expired).toHaveLength(0);
+    });
+
+    it("excludes entries already clawed back (idempotency)", async () => {
+      const entry = await ledger.credit("t1", Credit.fromCents(100), "purchase", {
+        expiresAt: "2020-01-01T00:00:00Z",
+      });
+
+      // Simulate a prior expiry entry by posting with the expiry referenceId
+      await ledger.post({
+        entryType: "credit_expiry",
+        tenantId: "t1",
+        referenceId: `expiry:${entry.id}`,
+        lines: [
+          { accountCode: "2000:t1", amount: Credit.fromCents(100), side: "debit" },
+          { accountCode: "4060", amount: Credit.fromCents(100), side: "credit" },
+        ],
+      });
+
+      const expired = await ledger.expiredCredits(new Date().toISOString());
+      expect(expired).toHaveLength(0);
+    });
+  });
+
   // -----------------------------------------------------------------------
   // memberUsage()
   // -----------------------------------------------------------------------

package/src/credits/ledger.ts

@@ -172,6 +172,24 @@ export const DEBIT_TYPE_ACCOUNT: Record<DebitType, string> = {
   correction: "5070", // CR expense:correction
 };
 
+/**
+ * Entry types eligible for credit expiry (allowlist).
+ * Only journal entries with these types can be returned by expiredCredits().
+ * Derived from CreditType — if you add a new CreditType, add it here too.
+ */
+export const EXPIRABLE_CREDIT_TYPES = [
+  "signup_grant",
+  "admin_grant",
+  "purchase",
+  "bounty",
+  "referral",
+  "promo",
+  "community_dividend",
+  "affiliate_bonus",
+  "affiliate_match",
+  "correction",
+] as const satisfies readonly CreditType[];
+
 // ---------------------------------------------------------------------------
 // System account seeds
 // ---------------------------------------------------------------------------
@@ -750,7 +768,10 @@ export class DrizzleLedger implements ILedger {
         and(
           isNotNull(sql`${journalEntries.metadata}->>'expiresAt'`),
           sql`(${journalEntries.metadata}->>'expiresAt') <= ${now}`,
-          sql`${journalEntries.entryType} NOT IN ('credit_expiry', 'bot_runtime', 'adapter_usage', 'addon', 'refund')`,
+          sql`${journalEntries.entryType} IN (${sql.join(
+            EXPIRABLE_CREDIT_TYPES.map((t) => sql`${t}`),
+            sql`, `,
+          )})`,
         ),
       );