@wopr-network/platform-core 0.1.0

package/dist/credits/credit-ledger.test.js

@@ -0,0 +1,203 @@
+/**
+ * Tests for CreditLedger — including the allowNegative debit parameter (WOP-821).
+ */
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { CreditLedger, InsufficientBalanceError } from "./credit-ledger.js";
+// TOP OF FILE - shared across ALL describes
+let pool;
+let db;
+beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+});
+afterAll(async () => {
+    await pool.close();
+});
+describe("CreditLedger core methods", () => {
+    let ledger;
+    beforeEach(async () => {
+        await truncateAllTables(pool);
+        ledger = new CreditLedger(db);
+    });
+    // --- credit() ---
+    describe("credit()", () => {
+        it("happy path: credits a tenant and returns correct transaction fields", async () => {
+            const txn = await ledger.credit("t1", Credit.fromCents(100), "purchase", "Initial deposit", "ref-001", "stripe", "user-abc");
+            expect(txn.tenantId).toBe("t1");
+            expect(txn.amount.toCents()).toBe(100);
+            expect(txn.balanceAfter.toCents()).toBe(100);
+            expect(txn.type).toBe("purchase");
+            expect(txn.description).toBe("Initial deposit");
+            expect(txn.referenceId).toBe("ref-001");
+            expect(txn.fundingSource).toBe("stripe");
+            expect(txn.attributedUserId).toBe("user-abc");
+            expect(txn.id).toEqual(expect.any(String));
+            expect(txn.createdAt).toEqual(expect.any(String));
+        });
+        it("multiple credits accumulate balance correctly", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase");
+            await ledger.credit("t1", Credit.fromCents(50), "promo");
+            const bal = await ledger.balance("t1");
+            expect(bal.toCents()).toBe(150);
+        });
+        it("rejects zero amount", async () => {
+            await expect(ledger.credit("t1", Credit.fromCents(0), "purchase")).rejects.toThrow("amount must be positive for credits");
+        });
+        it("rejects negative amount", async () => {
+            await expect(ledger.credit("t1", Credit.fromRaw(-1), "purchase")).rejects.toThrow("amount must be positive for credits");
+        });
+        it("optional fields default to null", async () => {
+            const txn = await ledger.credit("t1", Credit.fromCents(10), "signup_grant");
+            expect(txn.description).toBeNull();
+            expect(txn.referenceId).toBeNull();
+            expect(txn.fundingSource).toBeNull();
+            expect(txn.attributedUserId).toBeNull();
+        });
+    });
+    // --- balance() ---
+    describe("balance()", () => {
+        it("returns Credit.ZERO for a tenant with no transactions", async () => {
+            const bal = await ledger.balance("nonexistent");
+            expect(bal.toCents()).toBe(0);
+            expect(bal.isZero()).toBe(true);
+        });
+        it("reflects credits and debits accurately", async () => {
+            await ledger.credit("t1", Credit.fromCents(200), "purchase");
+            await ledger.debit("t1", Credit.fromCents(50), "bot_runtime");
+            const bal = await ledger.balance("t1");
+            expect(bal.toCents()).toBe(150);
+        });
+    });
+    // --- history() ---
+    describe("history()", () => {
+        it("returns transactions in reverse chronological order (newest first)", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase", "first");
+            await ledger.credit("t1", Credit.fromCents(200), "promo", "second");
+            await ledger.debit("t1", Credit.fromCents(50), "bot_runtime", "third");
+            const hist = await ledger.history("t1");
+            expect(hist).toHaveLength(3);
+            // newest first
+            expect(hist[0].description).toBe("third");
+            expect(hist[1].description).toBe("second");
+            expect(hist[2].description).toBe("first");
+        });
+        it("all CreditTransaction fields are populated", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase", "desc", "ref-1", "stripe", "user-1");
+            const hist = await ledger.history("t1");
+            expect(hist).toHaveLength(1);
+            const txn = hist[0];
+            expect(txn.id).toEqual(expect.any(String));
+            expect(txn.tenantId).toBe("t1");
+            expect(txn.amount.toCents()).toBe(100);
+            expect(txn.balanceAfter.toCents()).toBe(100);
+            expect(txn.type).toBe("purchase");
+            expect(txn.description).toBe("desc");
+            expect(txn.referenceId).toBe("ref-1");
+            expect(txn.fundingSource).toBe("stripe");
+            expect(txn.attributedUserId).toBe("user-1");
+            expect(txn.createdAt).toEqual(expect.any(String));
+        });
+        it("respects limit and offset for pagination", async () => {
+            // Insert 5 transactions
+            for (let i = 1; i <= 5; i++) {
+                await ledger.credit("t1", Credit.fromCents(10 * i), "purchase", `txn-${i}`);
+            }
+            const page1 = await ledger.history("t1", { limit: 2, offset: 0 });
+            expect(page1).toHaveLength(2);
+            expect(page1[0].description).toBe("txn-5"); // newest first
+            expect(page1[1].description).toBe("txn-4");
+            const page2 = await ledger.history("t1", { limit: 2, offset: 2 });
+            expect(page2).toHaveLength(2);
+            expect(page2[0].description).toBe("txn-3");
+            expect(page2[1].description).toBe("txn-2");
+        });
+        it("filters by type when provided", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase", "buy");
+            await ledger.credit("t1", Credit.fromCents(50), "promo", "free");
+            await ledger.debit("t1", Credit.fromCents(10), "bot_runtime", "usage");
+            const purchases = await ledger.history("t1", { type: "purchase" });
+            expect(purchases).toHaveLength(1);
+            expect(purchases[0].description).toBe("buy");
+        });
+        it("returns empty array for tenant with no transactions", async () => {
+            const hist = await ledger.history("nonexistent");
+            expect(hist).toEqual([]);
+        });
+    });
+    // --- hasReferenceId() ---
+    describe("hasReferenceId()", () => {
+        it("returns false for a reference ID that does not exist", async () => {
+            expect(await ledger.hasReferenceId("nonexistent-ref")).toBe(false);
+        });
+        it("returns true for a reference ID used in a credit", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase", "desc", "ref-unique");
+            expect(await ledger.hasReferenceId("ref-unique")).toBe(true);
+        });
+        it("returns true for a reference ID used in a debit", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase");
+            await ledger.debit("t1", Credit.fromCents(10), "bot_runtime", "desc", "debit-ref");
+            expect(await ledger.hasReferenceId("debit-ref")).toBe(true);
+        });
+        it("detects reference IDs across different tenants", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase", "desc", "cross-tenant-ref");
+            // hasReferenceId is global, not tenant-scoped
+            expect(await ledger.hasReferenceId("cross-tenant-ref")).toBe(true);
+        });
+    });
+    // --- tenantsWithBalance() ---
+    describe("tenantsWithBalance()", () => {
+        it("returns empty array when no tenants exist", async () => {
+            const result = await ledger.tenantsWithBalance();
+            expect(result).toEqual([]);
+        });
+        it("returns only tenants with positive balance", async () => {
+            // t1: positive balance (100 cents)
+            await ledger.credit("t1", Credit.fromCents(100), "purchase");
+            // t2: zero balance (credit then debit same amount)
+            await ledger.credit("t2", Credit.fromCents(50), "purchase");
+            await ledger.debit("t2", Credit.fromCents(50), "bot_runtime");
+            // t3: negative balance (via allowNegative)
+            await ledger.credit("t3", Credit.fromCents(10), "purchase");
+            await ledger.debit("t3", Credit.fromCents(20), "bot_runtime", undefined, undefined, true);
+            // t4: positive balance (200 cents)
+            await ledger.credit("t4", Credit.fromCents(200), "signup_grant");
+            const result = await ledger.tenantsWithBalance();
+            const tenantIds = result.map((r) => r.tenantId).sort();
+            expect(tenantIds).toEqual(["t1", "t4"]);
+            const t1 = result.find((r) => r.tenantId === "t1");
+            expect(t1?.balance.toCents()).toBe(100);
+            const t4 = result.find((r) => r.tenantId === "t4");
+            expect(t4?.balance.toCents()).toBe(200);
+        });
+        it("excludes tenants with exactly zero balance", async () => {
+            await ledger.credit("t1", Credit.fromCents(100), "purchase");
+            await ledger.debit("t1", Credit.fromCents(100), "bot_runtime");
+            const result = await ledger.tenantsWithBalance();
+            expect(result).toEqual([]);
+        });
+    });
+});
+describe("CreditLedger.debit with allowNegative", () => {
+    let ledger;
+    beforeEach(async () => {
+        await truncateAllTables(pool);
+        ledger = new CreditLedger(db);
+    });
+    it("debit with allowNegative=false (default) throws InsufficientBalanceError when balance insufficient", async () => {
+        await ledger.credit("t1", Credit.fromCents(5), "purchase", "setup");
+        await expect(ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "test")).rejects.toThrow(InsufficientBalanceError);
+    });
+    it("debit with allowNegative=true allows negative balance", async () => {
+        await ledger.credit("t1", Credit.fromCents(5), "purchase", "setup");
+        const txn = await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "test", undefined, true);
+        expect(txn).not.toBeNull();
+        expect((await ledger.balance("t1")).toCents()).toBe(-5);
+    });
+    it("debit with allowNegative=true records correct transaction with negative amount and negative balanceAfter", async () => {
+        await ledger.credit("t1", Credit.fromCents(5), "purchase", "setup");
+        const txn = await ledger.debit("t1", Credit.fromCents(10), "adapter_usage", "test", undefined, true);
+        expect(txn.amount.toCents()).toBe(-10);
+        expect(txn.balanceAfter.toCents()).toBe(-5);
+    });
+});

package/dist/credits/credit-transaction-repository.d.ts

@@ -0,0 +1,17 @@
+import type { PlatformDb } from "../db/index.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 declare class DrizzleCreditTransactionRepository implements ICreditTransactionRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    existsByReferenceIdLike(pattern: string): Promise<boolean>;
+    sumPurchasesForPeriod(startTs: string, endTs: string): Promise<Credit>;
+    getActiveTenantIdsInWindow(startTs: string, endTs: string): Promise<string[]>;
+}

package/dist/credits/credit-transaction-repository.js

@@ -0,0 +1,35 @@
+import { and, eq, gte, lt, sql } from "drizzle-orm";
+import { creditTransactions } from "../db/schema/credits.js";
+import { Credit } from "./credit.js";
+export class DrizzleCreditTransactionRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async existsByReferenceIdLike(pattern) {
+        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, endTs) {
+        const row = (await this.db
+            .select({
+            total: sql `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, endTs) {
+        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/dist/credits/credit-transaction-repository.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/credits/credit-transaction-repository.test.js

@@ -0,0 +1,232 @@
+import crypto from "node:crypto";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+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;
+let db;
+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) {
+    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;
+    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/dist/credits/credit.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Credit value object with sub-cent precision.
+ *
+ * SCALE = 1,000,000,000 raw units per dollar (nano-dollars).
+ * All arithmetic operates on integer raw units -- no floating point
+ * in arithmetic paths. Math.round() is used only at input boundaries
+ * (fromDollars, fromCents, multiply).
+ *
+ * @example
+ * ```ts
+ * const charge = Credit.fromDollars(0.001); // 1,000,000 raw units
+ * const balance = Credit.fromCents(500);     // 5,000,000,000 raw units
+ * const remaining = balance.subtract(charge);
+ * ```
+ */
+export declare class Credit {
+    private readonly raw;
+    static readonly SCALE = 1000000000;
+    private constructor();
+    /** Zero credit (static readonly instance to avoid allocation per access). */
+    static readonly ZERO: Credit;
+    /** Create from dollar amount. Rounds to nearest raw unit. */
+    static fromDollars(dollars: number): Credit;
+    /** Create from cent amount. Rounds to nearest raw unit. */
+    static fromCents(cents: number): Credit;
+    private static readonly WARN_10K;
+    private static readonly WARN_100K;
+    private static readonly WARN_1M;
+    /** Create from raw integer units. Throws TypeError if not integer. */
+    static fromRaw(raw: number): Credit;
+    /** Zero credit (factory method alias for Credit.ZERO). */
+    static zero(): Credit;
+    /** Convert to dollars (floating point, for display only). */
+    toDollars(): number;
+    /** Convert to cents (floating point, for display only). */
+    toCents(): number;
+    /**
+     * Convert to cents, rounded to nearest integer (Math.round).
+     * Use for display values and API responses where exact cent is needed.
+     */
+    toCentsRounded(): number;
+    /**
+     * Convert to cents, floored to integer (Math.floor).
+     * Use when sending amounts to Stripe/Payram — floor avoids charging
+     * more than the displayed amount.
+     */
+    toCentsFloor(): number;
+    /** Display as dollar amount with two decimal places. */
+    toDisplayString(): string;
+    /** Raw integer units (what gets stored in the database). */
+    toRaw(): number;
+    /** Add another Credit, returning a new Credit. */
+    add(other: Credit): Credit;
+    /** Subtract another Credit, returning a new Credit (may be negative). */
+    subtract(other: Credit): Credit;
+    /** Multiply by a factor, rounding to nearest raw unit. */
+    multiply(factor: number): Credit;
+    /** True if this credit is negative. */
+    isNegative(): boolean;
+    /** True if this credit is exactly zero. */
+    isZero(): boolean;
+    /** True if this credit is greater than other. */
+    greaterThan(other: Credit): boolean;
+    /** True if this credit is less than other. */
+    lessThan(other: Credit): boolean;
+    /** True if this credit equals other. */
+    equals(other: Credit): boolean;
+    /** True if this credit is greater than or equal to other. */
+    greaterThanOrEqual(other: Credit): boolean;
+    /** True if this credit is less than or equal to other. */
+    lessThanOrEqual(other: Credit): boolean;
+    toString(): string;
+    /** Serialize to raw integer for JSON (API responses, database). */
+    toJSON(): number;
+}