@wopr-network/platform-core 1.39.5 → 1.39.7

package/dist/billing/stripe/stripe-payment-processor.test.js

@@ -62,6 +62,7 @@ function createMocks() {
         existsByReferenceIdLike: vi.fn(),
         sumPurchasesForPeriod: vi.fn(),
         getActiveTenantIdsInWindow: vi.fn(),
+        debitCapped: vi.fn(),
     };
     const autoTopupEventLog = {
         writeEvent: vi.fn(),

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

@@ -1,5 +1,4 @@
 import { logger } from "../config/logger.js";
-import { InsufficientBalanceError } from "./ledger.js";
 /**
  * Sweep expired credit grants and debit the original grant amount
  * (or remaining balance if partially consumed).
@@ -16,31 +15,26 @@ export async function runCreditExpiryCron(cfg) {
     const expiredGrants = await cfg.ledger.expiredCredits(cfg.now);
     for (const grant of expiredGrants) {
         try {
-            const balance = await cfg.ledger.balance(grant.tenantId);
-            if (balance.isZero()) {
-                result.skippedZeroBalance++;
-                continue;
-            }
-            // Debit the lesser of the original grant amount or current balance
-            const debitAmount = balance.lessThan(grant.amount) ? balance : grant.amount;
-            await cfg.ledger.debit(grant.tenantId, debitAmount, "credit_expiry", {
+            // debitCapped never throws InsufficientBalanceError — it caps at the
+            // available balance and returns null when balance is zero. The catch
+            // below handles unexpected errors (DB failures, constraint violations).
+            const entry = await cfg.ledger.debitCapped(grant.tenantId, grant.amount, "credit_expiry", {
                 description: `Expired credit grant reclaimed: ${grant.entryId}`,
                 referenceId: `expiry:${grant.entryId}`,
             });
+            if (entry === null) {
+                result.skippedZeroBalance++;
+                continue;
+            }
             result.processed++;
             if (!result.expired.includes(grant.tenantId)) {
                 result.expired.push(grant.tenantId);
             }
         }
         catch (err) {
-            if (err instanceof InsufficientBalanceError) {
-                result.skippedZeroBalance++;
-            }
-            else {
-                const msg = err instanceof Error ? err.message : String(err);
-                logger.error("Credit expiry failed", { tenantId: grant.tenantId, entryId: grant.entryId, error: msg });
-                result.errors.push(`${grant.tenantId}:${grant.entryId}: ${msg}`);
-            }
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error("Credit expiry failed", { tenantId: grant.tenantId, entryId: grant.entryId, error: msg });
+            result.errors.push(`${grant.tenantId}:${grant.entryId}: ${msg}`);
         }
     }
     if (result.processed > 0) {

package/dist/credits/ledger.d.ts

@@ -154,6 +154,12 @@ export interface ILedger {
     sumPurchasesForPeriod(startTs: string, endTs: string): Promise<Credit>;
     /** Get distinct tenantIds with a purchase entry in [startTs, endTs). */
     getActiveTenantIdsInWindow(startTs: string, endTs: string): Promise<string[]>;
+    /**
+     * Debit up to maxAmount from a tenant, capped at their current balance.
+     * Reads balance inside the transaction (TOCTOU-safe). Returns null if
+     * balance is zero (nothing to debit).
+     */
+    debitCapped(tenantId: string, maxAmount: Credit, type: DebitType, opts?: DebitOpts): Promise<JournalEntry | null>;
 }
 export declare class DrizzleLedger implements ILedger {
     private readonly db;
@@ -177,6 +183,7 @@ export declare class DrizzleLedger implements ILedger {
     post(input: PostEntryInput): Promise<JournalEntry>;
     credit(tenantId: string, amount: Credit, type: CreditType, opts?: CreditOpts): Promise<JournalEntry>;
     debit(tenantId: string, amount: Credit, type: DebitType, opts?: DebitOpts): Promise<JournalEntry>;
+    debitCapped(tenantId: string, maxAmount: Credit, type: DebitType, opts?: DebitOpts): Promise<JournalEntry | null>;
     balance(tenantId: string): Promise<Credit>;
     accountBalance(accountCode: string): Promise<Credit>;
     hasReferenceId(referenceId: string): Promise<boolean>;

package/dist/credits/ledger.js

@@ -327,6 +327,112 @@ export class DrizzleLedger {
             ],
         });
     }
+    async debitCapped(tenantId, maxAmount, type, opts) {
+        const creditAccountCode = DEBIT_TYPE_ACCOUNT[type];
+        const tenantAccountCode = `2000:${tenantId}`;
+        // Everything happens inside ONE transaction so the FOR UPDATE lock is held
+        // continuously from balance read through journal posting (TOCTOU-safe).
+        return this.db.transaction(async (tx) => {
+            // Step 1: Lock BOTH accounts in accountCode-sorted order to match post()'s
+            // lock ordering and prevent ABBA deadlocks. For type="refund" the credit
+            // account is "1000" which sorts before "2000:<tenant>", so we must lock it
+            // first — the same order post() would use.
+            const sortedCodes = [tenantAccountCode, creditAccountCode].sort();
+            const lockedIds = new Map();
+            for (const code of sortedCodes) {
+                if (code.startsWith("2000:")) {
+                    lockedIds.set(code, await this.ensureTenantAccountLocked(tx, code.slice(5)));
+                }
+                else {
+                    lockedIds.set(code, await this.resolveAccountLocked(tx, code));
+                }
+            }
+            const tenantAccountId = lockedIds.get(tenantAccountCode);
+            const creditAccountId = lockedIds.get(creditAccountCode);
+            if (!tenantAccountId || !creditAccountId) {
+                throw new Error("Failed to resolve account IDs during debitCapped");
+            }
+            // Step 2: Read balance while holding the lock.
+            const balRows = (await tx.execute(sql `SELECT ab.balance FROM account_balances ab
+            INNER JOIN accounts a ON a.id = ab.account_id
+            WHERE a.code = ${tenantAccountCode}`));
+            const currentBalance = Credit.fromRaw(Number(balRows.rows[0]?.balance ?? 0));
+            if (currentBalance.isZero()) {
+                return null;
+            }
+            // Step 3: Cap at lesser of maxAmount and currentBalance.
+            const debitAmount = currentBalance.lessThan(maxAmount) ? currentBalance : maxAmount;
+            // Step 4: Insert journal entry header.
+            const entryId = crypto.randomUUID();
+            const now = new Date().toISOString();
+            await tx.insert(journalEntries).values({
+                id: entryId,
+                postedAt: now,
+                entryType: type,
+                description: opts?.description ?? null,
+                referenceId: opts?.referenceId ?? null,
+                tenantId,
+                metadata: { attributedUserId: opts?.attributedUserId ?? null },
+                createdBy: opts?.createdBy ?? "system",
+            });
+            // Step 5: Both accounts already locked in step 1 — no additional locking needed.
+            // Step 6: Insert journal lines.
+            // Debit line (tenant liability account — reduces balance)
+            const debitLineId = crypto.randomUUID();
+            await tx.insert(journalLines).values({
+                id: debitLineId,
+                journalEntryId: entryId,
+                accountId: tenantAccountId,
+                amount: debitAmount.toRaw(),
+                side: "debit",
+            });
+            // Credit line (revenue/target account — increases balance)
+            const creditLineId = crypto.randomUUID();
+            await tx.insert(journalLines).values({
+                id: creditLineId,
+                journalEntryId: entryId,
+                accountId: creditAccountId,
+                amount: debitAmount.toRaw(),
+                side: "credit",
+            });
+            // Step 7: Update materialized balances.
+            // Tenant account is liability (normal_side=credit): debit decreases balance.
+            await tx
+                .update(accountBalances)
+                .set({
+                balance: sql `${accountBalances.balance} + ${-debitAmount.toRaw()}`,
+                lastUpdated: sql `(now())`,
+            })
+                .where(eq(accountBalances.accountId, tenantAccountId));
+            // Credit-side account: look up its normal_side to determine delta direction.
+            const acctRow = (await tx.execute(sql `SELECT normal_side FROM accounts WHERE id = ${creditAccountId}`));
+            const normalSide = acctRow.rows[0]?.normal_side;
+            if (!normalSide)
+                throw new Error(`Account ${creditAccountId} missing normal_side`);
+            const creditDelta = "credit" === normalSide ? debitAmount.toRaw() : -debitAmount.toRaw();
+            await tx
+                .update(accountBalances)
+                .set({
+                balance: sql `${accountBalances.balance} + ${creditDelta}`,
+                lastUpdated: sql `(now())`,
+            })
+                .where(eq(accountBalances.accountId, creditAccountId));
+            // Step 8: Return the journal entry.
+            return {
+                id: entryId,
+                postedAt: now,
+                entryType: type,
+                tenantId,
+                description: opts?.description ?? null,
+                referenceId: opts?.referenceId ?? null,
+                metadata: { attributedUserId: opts?.attributedUserId ?? null },
+                lines: [
+                    { accountCode: tenantAccountCode, amount: debitAmount, side: "debit" },
+                    { accountCode: creditAccountCode, amount: debitAmount, side: "credit" },
+                ],
+            };
+        });
+    }
     // -- Queries -------------------------------------------------------------
     async balance(tenantId) {
         const code = `2000:${tenantId}`;

package/dist/credits/ledger.test.js

@@ -578,4 +578,60 @@ describe("DrizzleLedger", () => {
             expect(tb.balanced).toBe(true);
         });
     });
+    // -----------------------------------------------------------------------
+    // debitCapped()
+    // -----------------------------------------------------------------------
+    describe("debitCapped()", () => {
+        it("caps debit at current balance when maxAmount exceeds balance", async () => {
+            await ledger.credit("tenant-cap", Credit.fromCents(300), "promo", {
+                description: "Test grant",
+            });
+            const entry = await ledger.debitCapped("tenant-cap", Credit.fromCents(500), // maxAmount > balance
+            "credit_expiry", { description: "Expiry test", referenceId: "expiry:test-cap" });
+            if (entry === null)
+                throw new Error("expected non-null entry");
+            // Should have debited 300 (the balance), not 500 (the maxAmount)
+            const debitLine = entry.lines.find((l) => l.accountCode === "2000:tenant-cap" && l.side === "debit");
+            if (!debitLine)
+                throw new Error("expected debit line");
+            expect(debitLine.amount.toCents()).toBe(300);
+            const balance = await ledger.balance("tenant-cap");
+            expect(balance.toCents()).toBe(0);
+        });
+        it("returns null when balance is zero", async () => {
+            const entry = await ledger.debitCapped("tenant-zero", Credit.fromCents(500), "credit_expiry", {
+                description: "Expiry test",
+                referenceId: "expiry:test-zero",
+            });
+            expect(entry).toBeNull();
+        });
+        it("debits exact maxAmount when balance exceeds it", async () => {
+            await ledger.credit("tenant-over", Credit.fromCents(1000), "purchase", {
+                description: "Big deposit",
+            });
+            const entry = await ledger.debitCapped("tenant-over", Credit.fromCents(300), "credit_expiry", {
+                description: "Partial expiry",
+                referenceId: "expiry:test-over",
+            });
+            if (entry === null)
+                throw new Error("expected non-null entry");
+            const debitLine = entry.lines.find((l) => l.accountCode === "2000:tenant-over" && l.side === "debit");
+            if (!debitLine)
+                throw new Error("expected debit line");
+            expect(debitLine.amount.toCents()).toBe(300);
+            const balance = await ledger.balance("tenant-over");
+            expect(balance.toCents()).toBe(700);
+        });
+        it("books balance correctly after capped debit (trial balance holds)", async () => {
+            await ledger.credit("tenant-tb", Credit.fromCents(200), "promo", {
+                description: "Small grant",
+            });
+            await ledger.debitCapped("tenant-tb", Credit.fromCents(500), "credit_expiry", {
+                description: "Expiry",
+                referenceId: "expiry:test-tb",
+            });
+            const tb = await ledger.trialBalance();
+            expect(tb.balanced).toBe(true);
+        });
+    });
 });

package/dist/fleet/fleet-manager.d.ts

@@ -53,20 +53,17 @@ export declare class FleetManager {
      */
     getInstance(id: string): Promise<Instance>;
     private buildInstance;
-    /**
-     * Restart: pull new image BEFORE restarting container to avoid downtime on pull failure.
-     * Valid from: running, stopped, exited, dead states.
-     * Throws InvalidStateTransitionError if the container is in an invalid state (e.g. paused).
-     * For remote bots, delegates to the node agent via NodeCommandBus.
-     */
-    restart(id: string): Promise<void>;
     /**
      * Remove a bot: stop container, remove it, optionally remove volumes, delete profile.
      * For remote bots, delegates stop+remove to the node agent via NodeCommandBus.
+     * Container removal is delegated to Instance.remove(); fleet-level cleanup
+     * (profile store, network policy) stays here.
      */
     remove(id: string, removeVolumes?: boolean): Promise<void>;
     /**
      * Get live status of a single bot.
+     * Delegates to Instance.status() which returns a full BotStatus.
+     * Falls back to offline status when no container exists.
      */
     status(id: string): Promise<BotStatus>;
     /**
@@ -78,58 +75,40 @@ export declare class FleetManager {
      */
     listByTenant(tenantId: string): Promise<BotStatus[]>;
     /**
-     * Get container logs.
+     * Get container logs. Delegates to Instance.logs().
      */
     logs(id: string, tail?: number): Promise<string>;
     /**
      * Stream container logs in real-time (follow mode).
-     * Returns a Node.js ReadableStream that emits plain-text log chunks (already demultiplexed).
      * For remote bots, proxies via node-agent bot.logs command and returns a one-shot stream.
-     * Caller is responsible for destroying the stream when done.
+     * For local bots, delegates to Instance.logStream().
      */
     logStream(id: string, opts: {
         since?: string;
         tail?: number;
     }): Promise<NodeJS.ReadableStream>;
-    /** Fields that require container recreation when changed. */
-    private static readonly CONTAINER_FIELDS;
-    /**
-     * Update a bot profile. Only recreates the container if container-relevant
-     * fields changed. Rolls back the profile if container recreation fails.
-     */
-    update(id: string, updates: Partial<Omit<BotProfile, "id">>): Promise<BotProfile>;
     /**
-     * Get disk usage for a bot's /data volume.
-     * Returns null if the container is not running or exec fails.
+     * Get disk usage for a bot's /data volume. Delegates to Instance.getVolumeUsage().
      */
     getVolumeUsage(id: string): Promise<{
         usedBytes: number;
         totalBytes: number;
         availableBytes: number;
     } | null>;
-    /** Get the underlying profile store */
-    get profiles(): IProfileStore;
+    /** Fields that require container recreation when changed. */
+    private static readonly CONTAINER_FIELDS;
     /**
-     * Assert that a container's current state is valid for the requested operation.
-     * Guards against undefined/null Status values from Docker (uses "unknown" as fallback).
-     * Throws InvalidStateTransitionError when the state is not in validStates.
+     * Update a bot profile. Only recreates the container if container-relevant
+     * fields changed. Rolls back the profile if container recreation fails.
      */
-    private assertValidState;
+    update(id: string, updates: Partial<Omit<BotProfile, "id">>): Promise<BotProfile>;
+    /** Get the underlying profile store */
+    get profiles(): IProfileStore;
     private pullImage;
     private createContainer;
     private findContainer;
     private statusForProfile;
-    private buildStatus;
-    private offlineStatus;
-    private getStats;
 }
 export declare class BotNotFoundError extends Error {
     constructor(id: string);
 }
-export declare class InvalidStateTransitionError extends Error {
-    readonly botId: string;
-    readonly operation: string;
-    readonly currentState: string;
-    readonly validStates: string[];
-    constructor(botId: string, operation: string, currentState: string, validStates: string[]);
-}