@wopr-network/platform-core 0.1.0

package/src/credits/credit-transaction-repository.test.ts

@@ -0,0 +1,274 @@
+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 { creditTransactions } from "../db/schema/credits.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { DrizzleCreditTransactionRepository } from "./credit-transaction-repository.js";
+
+let pool: PGlite;
+let db: PlatformDb;
+
+beforeAll(async () => {
+  ({ db, pool } = await createTestDb());
+  await beginTestTransaction(pool);
+});
+
+afterAll(async () => {
+  await endTestTransaction(pool);
+  await pool.close();
+});
+
+/** Seed a credit_transactions row directly. */
+async function seedTx(opts: {
+  tenantId: string;
+  amount: Credit;
+  type: string;
+  createdAt?: string;
+  referenceId?: string;
+  balanceAfter?: Credit;
+}): Promise<void> {
+  await db.insert(creditTransactions).values({
+    id: crypto.randomUUID(),
+    tenantId: opts.tenantId,
+    amount: opts.amount,
+    balanceAfter: opts.balanceAfter ?? opts.amount,
+    type: opts.type,
+    description: "test",
+    referenceId: opts.referenceId ?? null,
+    createdAt: opts.createdAt ?? new Date().toISOString(),
+  });
+}
+
+describe("DrizzleCreditTransactionRepository", () => {
+  let repo: DrizzleCreditTransactionRepository;
+
+  beforeEach(async () => {
+    await rollbackTestTransaction(pool);
+    repo = new DrizzleCreditTransactionRepository(db);
+  });
+
+  describe("existsByReferenceIdLike()", () => {
+    it("returns false when no transactions exist", async () => {
+      const result = await repo.existsByReferenceIdLike("div-%");
+      expect(result).toBe(false);
+    });
+
+    it("returns true when a matching referenceId exists", async () => {
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(100),
+        type: "purchase",
+        referenceId: "div-2026-01-01",
+      });
+
+      const result = await repo.existsByReferenceIdLike("div-%");
+      expect(result).toBe(true);
+    });
+
+    it("returns false when no referenceId matches the pattern", async () => {
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(100),
+        type: "purchase",
+        referenceId: "purchase-abc",
+      });
+
+      const result = await repo.existsByReferenceIdLike("div-%");
+      expect(result).toBe(false);
+    });
+
+    it("matches partial patterns with wildcards", async () => {
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(50),
+        type: "community_dividend",
+        referenceId: "div-2026-02-15-t1",
+      });
+
+      expect(await repo.existsByReferenceIdLike("div-2026-02-%")).toBe(true);
+      expect(await repo.existsByReferenceIdLike("div-2026-03-%")).toBe(false);
+    });
+  });
+
+  describe("sumPurchasesForPeriod()", () => {
+    it("returns Credit.ZERO when no transactions exist", async () => {
+      const sum = await repo.sumPurchasesForPeriod("2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z");
+      expect(sum.toRaw()).toBe(0);
+    });
+
+    it("sums only purchase-type transactions", async () => {
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(100),
+        type: "purchase",
+        createdAt: "2026-01-15T12:00:00Z",
+      });
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(200),
+        type: "signup_grant",
+        createdAt: "2026-01-15T12:00:00Z",
+      });
+
+      const sum = await repo.sumPurchasesForPeriod("2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z");
+      expect(sum.toRaw()).toBe(Credit.fromCents(100).toRaw());
+    });
+
+    it("respects half-open interval [start, end)", async () => {
+      // Exactly at start — included
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(10),
+        type: "purchase",
+        createdAt: "2026-01-01T00:00:00Z",
+      });
+      // Inside window
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(20),
+        type: "purchase",
+        createdAt: "2026-01-15T00:00:00Z",
+      });
+      // Exactly at end — excluded
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(40),
+        type: "purchase",
+        createdAt: "2026-02-01T00:00:00Z",
+      });
+
+      const sum = await repo.sumPurchasesForPeriod("2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z");
+      expect(sum.toRaw()).toBe(Credit.fromCents(30).toRaw()); // 10 + 20, not 40
+    });
+
+    it("sums across all tenants (not tenant-scoped)", async () => {
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(50),
+        type: "purchase",
+        createdAt: "2026-01-10T00:00:00Z",
+      });
+      await seedTx({
+        tenantId: "t2",
+        amount: Credit.fromCents(75),
+        type: "purchase",
+        createdAt: "2026-01-10T00:00:00Z",
+      });
+
+      const sum = await repo.sumPurchasesForPeriod("2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z");
+      expect(sum.toRaw()).toBe(Credit.fromCents(125).toRaw()); // 50 + 75
+    });
+  });
+
+  describe("getActiveTenantIdsInWindow()", () => {
+    it("returns empty array when no transactions exist", async () => {
+      const ids = await repo.getActiveTenantIdsInWindow("2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z");
+      expect(ids).toEqual([]);
+    });
+
+    it("returns distinct tenantIds with purchase transactions in window", async () => {
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(10),
+        type: "purchase",
+        createdAt: "2026-01-10T00:00:00Z",
+      });
+      // t1 again — should not duplicate
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(20),
+        type: "purchase",
+        createdAt: "2026-01-11T00:00:00Z",
+      });
+      await seedTx({
+        tenantId: "t2",
+        amount: Credit.fromCents(30),
+        type: "purchase",
+        createdAt: "2026-01-12T00:00:00Z",
+      });
+
+      const ids = await repo.getActiveTenantIdsInWindow("2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z");
+      expect(ids.sort()).toEqual(["t1", "t2"]);
+    });
+
+    it("excludes non-purchase transaction types", async () => {
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(100),
+        type: "signup_grant",
+        createdAt: "2026-01-10T00:00:00Z",
+      });
+
+      const ids = await repo.getActiveTenantIdsInWindow("2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z");
+      expect(ids).toEqual([]);
+    });
+
+    it("respects half-open interval [start, end)", async () => {
+      // Before window
+      await seedTx({
+        tenantId: "t-before",
+        amount: Credit.fromCents(10),
+        type: "purchase",
+        createdAt: "2025-12-31T23:59:59Z",
+      });
+      // At start — included
+      await seedTx({
+        tenantId: "t-start",
+        amount: Credit.fromCents(10),
+        type: "purchase",
+        createdAt: "2026-01-01T00:00:00Z",
+      });
+      // At end — excluded
+      await seedTx({
+        tenantId: "t-end",
+        amount: Credit.fromCents(10),
+        type: "purchase",
+        createdAt: "2026-02-01T00:00:00Z",
+      });
+
+      const ids = await repo.getActiveTenantIdsInWindow("2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z");
+      expect(ids).toEqual(["t-start"]);
+    });
+  });
+
+  describe("referenceId uniqueness", () => {
+    it("rejects duplicate referenceId (database unique constraint)", async () => {
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(100),
+        type: "purchase",
+        referenceId: "unique-ref-1",
+      });
+
+      await expect(
+        seedTx({
+          tenantId: "t1",
+          amount: Credit.fromCents(200),
+          type: "purchase",
+          referenceId: "unique-ref-1",
+        }),
+      ).rejects.toThrow(); // PG unique constraint violation
+    });
+
+    it("allows null referenceId on multiple rows", async () => {
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(100),
+        type: "purchase",
+        referenceId: undefined, // null
+      });
+      await seedTx({
+        tenantId: "t1",
+        amount: Credit.fromCents(200),
+        type: "purchase",
+        referenceId: undefined, // null
+      });
+
+      // Both inserted — no constraint violation for nulls
+      const result = await repo.existsByReferenceIdLike("%");
+      expect(result).toBe(false); // LIKE '%' won't match null referenceIds
+    });
+  });
+});

package/src/credits/credit-transaction-repository.ts

@@ -0,0 +1,62 @@
+import { and, eq, gte, lt, sql } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+import { creditTransactions } from "../db/schema/credits.js";
+import { Credit } from "./credit.js";
+
+export interface ICreditTransactionRepository {
+  /** Check if any transaction exists with a referenceId matching a LIKE pattern. */
+  existsByReferenceIdLike(pattern: string): Promise<boolean>;
+  /** Sum amount for 'purchase' transactions within [startTs, endTs). */
+  sumPurchasesForPeriod(startTs: string, endTs: string): Promise<Credit>;
+  /** Get distinct tenantIds that had a 'purchase' transaction within [startTs, endTs). */
+  getActiveTenantIdsInWindow(startTs: string, endTs: string): Promise<string[]>;
+}
+
+export class DrizzleCreditTransactionRepository implements ICreditTransactionRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async existsByReferenceIdLike(pattern: string): Promise<boolean> {
+    const row = (
+      await this.db
+        .select({ id: creditTransactions.id })
+        .from(creditTransactions)
+        .where(sql`${creditTransactions.referenceId} LIKE ${pattern}`)
+        .limit(1)
+    )[0];
+    return row != null;
+  }
+
+  async sumPurchasesForPeriod(startTs: string, endTs: string): Promise<Credit> {
+    const row = (
+      await this.db
+        .select({
+          total: sql<number>`COALESCE(SUM(${creditTransactions.amount}), 0)`,
+        })
+        .from(creditTransactions)
+        .where(
+          and(
+            eq(creditTransactions.type, "purchase"),
+            gte(creditTransactions.createdAt, startTs),
+            lt(creditTransactions.createdAt, endTs),
+          ),
+        )
+    )[0];
+    return Credit.fromRaw(Math.round(row?.total ?? 0));
+  }
+
+  async getActiveTenantIdsInWindow(startTs: string, endTs: string): Promise<string[]> {
+    const rows = await this.db
+      .selectDistinct({
+        tenantId: creditTransactions.tenantId,
+      })
+      .from(creditTransactions)
+      .where(
+        and(
+          eq(creditTransactions.type, "purchase"),
+          gte(creditTransactions.createdAt, startTs),
+          lt(creditTransactions.createdAt, endTs),
+        ),
+      );
+    return rows.map((r) => r.tenantId);
+  }
+}

package/src/credits/credit.test.ts

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