codebuff 1.0.247 → 1.0.249

package/dist/common/billing/balance-calculator.d.ts

@@ -0,0 +1,57 @@
+import db from '../db';
+import { GrantType } from '../db/schema';
+export interface CreditBalance {
+    totalRemaining: number;
+    totalDebt: number;
+    netBalance: number;
+    breakdown: Partial<Record<GrantType, number>>;
+    principals: Partial<Record<GrantType, number>>;
+}
+export interface CreditUsageAndBalance {
+    usageThisCycle: number;
+    balance: CreditBalance;
+}
+export interface CreditConsumptionResult {
+    consumed: number;
+    fromPurchased: number;
+}
+type DbConn = Pick<typeof db, 'select' | 'update'>;
+/**
+ * Gets active grants for a user, ordered by expiration (soonest first), then priority, and creation date.
+ * Added optional `conn` param so callers inside a transaction can supply their TX object.
+ */
+export declare function getOrderedActiveGrants(userId: string, now: Date, conn?: DbConn): Promise<{
+    created_at: Date;
+    type: import("../types/grant").GrantType;
+    expires_at: Date | null;
+    operation_id: string;
+    user_id: string;
+    principal: number;
+    balance: number;
+    description: string | null;
+    priority: number;
+}[]>;
+/**
+ * Calculates both the current balance and usage in this cycle in a single query.
+ * This is more efficient than calculating them separately.
+ */
+export declare function calculateUsageAndBalance(userId: string, quotaResetDate: Date, now?: Date): Promise<CreditUsageAndBalance>;
+/**
+ * Updates the remaining amounts in credit grants after consumption.
+ * Follows priority order strictly - higher priority grants (lower number) are consumed first.
+ * Returns details about credit consumption including how many came from purchased credits.
+ *
+ * Uses SERIALIZABLE isolation to prevent concurrent modifications that could lead to
+ * incorrect credit usage (e.g., "double spending" credits).
+ *
+ * @param userId The ID of the user
+ * @param creditsToConsume Number of credits being consumed
+ * @returns Promise resolving to number of credits consumed
+ */
+export declare function consumeCredits(userId: string, creditsToConsume: number): Promise<CreditConsumptionResult>;
+/**
+ * Calculate the total credits used during the current billing cycle for a user
+ * by summing the difference between initial and remaining amounts for all relevant grants.
+ */
+export declare function calculateUsageThisCycle(userId: string, quotaResetDate: Date): Promise<number>;
+export {};

package/dist/common/billing/balance-calculator.js

@@ -0,0 +1,218 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOrderedActiveGrants = getOrderedActiveGrants;
+exports.calculateUsageAndBalance = calculateUsageAndBalance;
+exports.consumeCredits = consumeCredits;
+exports.calculateUsageThisCycle = calculateUsageThisCycle;
+const db_1 = __importDefault(require("../db"));
+const schema = __importStar(require("../db/schema"));
+const drizzle_orm_1 = require("drizzle-orm");
+const logger_1 = require("../util/logger");
+const transaction_1 = require("../db/transaction");
+/**
+ * Gets active grants for a user, ordered by expiration (soonest first), then priority, and creation date.
+ * Added optional `conn` param so callers inside a transaction can supply their TX object.
+ */
+async function getOrderedActiveGrants(userId, now, conn = db_1.default // use DbConn instead of typeof db
+) {
+    return conn
+        .select()
+        .from(schema.creditLedger)
+        .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema.creditLedger.user_id, userId), (0, drizzle_orm_1.or)((0, drizzle_orm_1.isNull)(schema.creditLedger.expires_at), (0, drizzle_orm_1.gt)(schema.creditLedger.expires_at, now))))
+        .orderBy(
+    // Use grants based on priority, then expiration date, then creation date
+    (0, drizzle_orm_1.asc)(schema.creditLedger.priority), (0, drizzle_orm_1.asc)(schema.creditLedger.expires_at), (0, drizzle_orm_1.asc)(schema.creditLedger.created_at));
+}
+/**
+ * Updates a single grant's balance and logs the change.
+ */
+async function updateGrantBalance(userId, grant, consumed, newBalance, tx) {
+    await tx
+        .update(schema.creditLedger)
+        .set({ balance: newBalance })
+        .where((0, drizzle_orm_1.eq)(schema.creditLedger.operation_id, grant.operation_id));
+    logger_1.logger.debug({
+        userId,
+        grantId: grant.operation_id,
+        grantType: grant.type,
+        consumed,
+        remaining: newBalance,
+        expiresAt: grant.expires_at,
+    }, 'Updated grant remaining amount after consumption');
+}
+/**
+ * Consumes credits from a list of ordered grants.
+ */
+async function consumeFromOrderedGrants(userId, creditsToConsume, grants, tx) {
+    let remainingToConsume = creditsToConsume;
+    let consumed = 0;
+    let fromPurchased = 0;
+    // First pass: try to repay any debt
+    for (const grant of grants) {
+        if (grant.balance < 0 && remainingToConsume > 0) {
+            const debtAmount = Math.abs(grant.balance);
+            const repayAmount = Math.min(debtAmount, remainingToConsume);
+            const newBalance = grant.balance + repayAmount;
+            remainingToConsume -= repayAmount;
+            consumed += repayAmount;
+            await updateGrantBalance(userId, grant, -repayAmount, newBalance, tx);
+            logger_1.logger.debug({ userId, grantId: grant.operation_id, repayAmount, newBalance }, 'Repaid debt in grant');
+        }
+    }
+    // Second pass: consume from positive balances
+    for (const grant of grants) {
+        if (remainingToConsume <= 0)
+            break;
+        if (grant.balance <= 0)
+            continue;
+        const consumeFromThisGrant = Math.min(remainingToConsume, grant.balance);
+        const newBalance = grant.balance - consumeFromThisGrant;
+        remainingToConsume -= consumeFromThisGrant;
+        consumed += consumeFromThisGrant;
+        // Track consumption from purchased credits
+        if (grant.type === 'purchase') {
+            fromPurchased += consumeFromThisGrant;
+        }
+        await updateGrantBalance(userId, grant, consumeFromThisGrant, newBalance, tx);
+    }
+    // If we still have remaining to consume and no grants left, create debt in the last grant
+    if (remainingToConsume > 0 && grants.length > 0) {
+        const lastGrant = grants[grants.length - 1];
+        if (lastGrant.balance <= 0) {
+            const newBalance = lastGrant.balance - remainingToConsume;
+            await updateGrantBalance(userId, lastGrant, remainingToConsume, newBalance, tx);
+            consumed += remainingToConsume;
+            logger_1.logger.warn({
+                userId,
+                grantId: lastGrant.operation_id,
+                requested: remainingToConsume,
+                consumed: remainingToConsume,
+                newDebt: Math.abs(newBalance),
+            }, 'Created new debt in grant');
+        }
+    }
+    return { consumed, fromPurchased };
+}
+/**
+ * Calculates both the current balance and usage in this cycle in a single query.
+ * This is more efficient than calculating them separately.
+ */
+async function calculateUsageAndBalance(userId, quotaResetDate, now = new Date()) {
+    // Get all relevant grants in one query
+    const grants = await getOrderedActiveGrants(userId, now);
+    // Initialize balance structure
+    const balance = {
+        totalRemaining: 0,
+        totalDebt: 0,
+        netBalance: 0,
+        breakdown: {},
+        principals: {},
+    };
+    // Calculate both metrics in one pass
+    let usageThisCycle = 0;
+    let totalPositiveBalance = 0;
+    let totalDebt = 0;
+    // First pass: calculate initial totals and usage
+    for (const grant of grants) {
+        const grantType = grant.type;
+        // Calculate usage if grant was active in this cycle
+        if (grant.created_at > quotaResetDate ||
+            !grant.expires_at ||
+            grant.expires_at > quotaResetDate) {
+            usageThisCycle += grant.principal - grant.balance;
+        }
+        // Add to balance if grant is currently active
+        if (!grant.expires_at || grant.expires_at > now) {
+            if (grant.balance > 0) {
+                totalPositiveBalance += grant.balance;
+                balance.breakdown[grantType] =
+                    (balance.breakdown[grantType] || 0) + grant.balance;
+                balance.principals[grantType] =
+                    (balance.principals[grantType] || 0) + grant.principal;
+            }
+            else if (grant.balance < 0) {
+                totalDebt += Math.abs(grant.balance);
+            }
+        }
+    }
+    // Perform in-memory settlement if there's both debt and positive balance
+    if (totalDebt > 0 && totalPositiveBalance > 0) {
+        const settlementAmount = Math.min(totalDebt, totalPositiveBalance);
+        logger_1.logger.debug({ userId, totalDebt, totalPositiveBalance, settlementAmount }, 'Performing in-memory settlement');
+        // After settlement:
+        totalPositiveBalance -= settlementAmount;
+        totalDebt -= settlementAmount;
+    }
+    // Set final balance values after settlement
+    balance.totalRemaining = totalPositiveBalance;
+    balance.totalDebt = totalDebt;
+    balance.netBalance = totalPositiveBalance - totalDebt;
+    logger_1.logger.debug({ userId, balance, usageThisCycle, grantsCount: grants.length }, 'Calculated usage and settled balance');
+    return { usageThisCycle, balance };
+}
+/**
+ * Updates the remaining amounts in credit grants after consumption.
+ * Follows priority order strictly - higher priority grants (lower number) are consumed first.
+ * Returns details about credit consumption including how many came from purchased credits.
+ *
+ * Uses SERIALIZABLE isolation to prevent concurrent modifications that could lead to
+ * incorrect credit usage (e.g., "double spending" credits).
+ *
+ * @param userId The ID of the user
+ * @param creditsToConsume Number of credits being consumed
+ * @returns Promise resolving to number of credits consumed
+ */
+async function consumeCredits(userId, creditsToConsume) {
+    return await (0, transaction_1.withSerializableTransaction)(async (tx) => {
+        const now = new Date();
+        const activeGrants = await getOrderedActiveGrants(userId, now, tx);
+        if (activeGrants.length === 0) {
+            logger_1.logger.error({ userId, creditsToConsume }, 'No active grants found to consume credits from');
+            throw new Error('No active grants found');
+        }
+        const result = await consumeFromOrderedGrants(userId, creditsToConsume, activeGrants, tx);
+        return result;
+    }, { userId, creditsToConsume });
+}
+/**
+ * Calculate the total credits used during the current billing cycle for a user
+ * by summing the difference between initial and remaining amounts for all relevant grants.
+ */
+async function calculateUsageThisCycle(userId, quotaResetDate) {
+    const usageResult = await db_1.default
+        .select({
+        totalUsed: (0, drizzle_orm_1.sql) `COALESCE(SUM(${schema.creditLedger.principal} - ${schema.creditLedger.balance}), 0)`,
+    })
+        .from(schema.creditLedger)
+        .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema.creditLedger.user_id, userId), 
+    // Grant was created during this cycle OR expires after this cycle starts (including never expires)
+    (0, drizzle_orm_1.or)((0, drizzle_orm_1.gt)(schema.creditLedger.created_at, quotaResetDate), (0, drizzle_orm_1.and)((0, drizzle_orm_1.or)((0, drizzle_orm_1.isNull)(schema.creditLedger.expires_at), (0, drizzle_orm_1.gt)(schema.creditLedger.expires_at, quotaResetDate))))));
+    return usageResult[0].totalUsed;
+}
+//# sourceMappingURL=balance-calculator.js.map

package/dist/common/billing/balance-calculator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance-calculator.js","sourceRoot":"","sources":["../../src/billing/balance-calculator.ts"],"names":[],"mappings":"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"}

package/dist/common/billing/conversion.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Determines the cost of one internal credit in USD cents for a given user.
+ * TODO: Enhance this function to fetch user's plan and apply plan-specific rates.
+ *
+ * @param userId - The ID of the user (currently unused, for future enhancement).
+ * @returns The cost of one internal credit in cents.
+ */
+export declare function getUserCostPerCredit(userId: string | undefined): Promise<number>;
+export { convertCreditsToUsdCents, convertStripeGrantAmountToCredits } from './credit-conversion';

package/dist/common/billing/conversion.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertStripeGrantAmountToCredits = exports.convertCreditsToUsdCents = void 0;
+exports.getUserCostPerCredit = getUserCostPerCredit;
+/**
+ * Determines the cost of one internal credit in USD cents for a given user.
+ * TODO: Enhance this function to fetch user's plan and apply plan-specific rates.
+ *
+ * @param userId - The ID of the user (currently unused, for future enhancement).
+ * @returns The cost of one internal credit in cents.
+ */
+async function getUserCostPerCredit(userId) {
+    // Placeholder: Currently 1 cent per credit for all users. Can adjust in the future based on user
+    return 1;
+}
+// Re-export the pure conversion functions
+var credit_conversion_1 = require("./credit-conversion");
+Object.defineProperty(exports, "convertCreditsToUsdCents", { enumerable: true, get: function () { return credit_conversion_1.convertCreditsToUsdCents; } });
+Object.defineProperty(exports, "convertStripeGrantAmountToCredits", { enumerable: true, get: function () { return credit_conversion_1.convertStripeGrantAmountToCredits; } });
+//# sourceMappingURL=conversion.js.map

package/dist/common/billing/conversion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversion.js","sourceRoot":"","sources":["../../src/billing/conversion.ts"],"names":[],"mappings":";;;AAUA,oDAKC;AAZD;;;;;;GAMG;AACI,KAAK,UAAU,oBAAoB,CACxC,MAA0B;IAE1B,iGAAiG;IACjG,OAAO,CAAC,CAAA;AACV,CAAC;AAED,0CAA0C;AAC1C,yDAAiG;AAAxF,6HAAA,wBAAwB,OAAA;AAAE,sIAAA,iCAAiC,OAAA"}

package/dist/common/billing/credit-conversion.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Gets the cost per credit for a user. Currently hardcoded to 1 cent per credit,
+ * but could be customized per user in the future.
+ */
+export declare function getUserCostPerCredit(userId: string | undefined): Promise<number>;
+/**
+ * Converts an internal credit system value to the equivalent monetary amount in USD cents,
+ * based on the user's cost per credit.
+ * Uses Math.ceil to ensure enough monetary value is calculated if rounding occurs.
+ *
+ * @param credits - The amount in internal credits.
+ * @param centsPerCredit - The user's effective cost per internal credit (in cents).
+ * @returns The equivalent amount in USD cents.
+ */
+export declare function convertCreditsToUsdCents(credits: number, centsPerCredit: number): number;
+/**
+ * Converts a Stripe grant amount (in the smallest currency unit, e.g., cents for USD)
+ * to the application's internal credit system units, based on the user's cost per credit.
+ *
+ * @param amountInSmallestUnit - The grant amount from Stripe, typically in cents.
+ * @param centsPerCredit - The user's effective cost per internal credit (in cents).
+ * @returns The equivalent amount in application credits. Uses Math.round for conversion.
+ */
+export declare function convertStripeGrantAmountToCredits(amountInSmallestUnit: number, centsPerCredit: number): number;

package/dist/common/billing/credit-conversion.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUserCostPerCredit = getUserCostPerCredit;
+exports.convertCreditsToUsdCents = convertCreditsToUsdCents;
+exports.convertStripeGrantAmountToCredits = convertStripeGrantAmountToCredits;
+/**
+ * Gets the cost per credit for a user. Currently hardcoded to 1 cent per credit,
+ * but could be customized per user in the future.
+ */
+async function getUserCostPerCredit(userId) {
+    return 1; // 1 cent per credit
+}
+/**
+ * Converts an internal credit system value to the equivalent monetary amount in USD cents,
+ * based on the user's cost per credit.
+ * Uses Math.ceil to ensure enough monetary value is calculated if rounding occurs.
+ *
+ * @param credits - The amount in internal credits.
+ * @param centsPerCredit - The user's effective cost per internal credit (in cents).
+ * @returns The equivalent amount in USD cents.
+ */
+function convertCreditsToUsdCents(credits, centsPerCredit) {
+    if (credits <= 0 || centsPerCredit <= 0) {
+        return 0;
+    }
+    // Total Cents = Credits * Cents per Credit
+    const cents = credits * centsPerCredit;
+    // Use Math.ceil for safety, ensuring we calculate enough monetary value.
+    return Math.ceil(cents);
+}
+/**
+ * Converts a Stripe grant amount (in the smallest currency unit, e.g., cents for USD)
+ * to the application's internal credit system units, based on the user's cost per credit.
+ *
+ * @param amountInSmallestUnit - The grant amount from Stripe, typically in cents.
+ * @param centsPerCredit - The user's effective cost per internal credit (in cents).
+ * @returns The equivalent amount in application credits. Uses Math.round for conversion.
+ */
+function convertStripeGrantAmountToCredits(amountInSmallestUnit, centsPerCredit) {
+    if (centsPerCredit <= 0) {
+        return 0;
+    }
+    // Credits = Total Cents / Cents per Credit
+    const credits = amountInSmallestUnit / centsPerCredit;
+    // Use Math.round for robustness
+    return Math.round(credits);
+}
+//# sourceMappingURL=credit-conversion.js.map

package/dist/common/billing/credit-conversion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credit-conversion.js","sourceRoot":"","sources":["../../src/billing/credit-conversion.ts"],"names":[],"mappings":";;AAIA,oDAEC;AAWD,4DAWC;AAUD,8EAWC;AAjDD;;;GAGG;AACI,KAAK,UAAU,oBAAoB,CAAC,MAA0B;IACnE,OAAO,CAAC,CAAA,CAAC,oBAAoB;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,wBAAwB,CACtC,OAAe,EACf,cAAsB;IAEtB,IAAI,OAAO,IAAI,CAAC,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;QACxC,OAAO,CAAC,CAAA;IACV,CAAC;IACD,2CAA2C;IAC3C,MAAM,KAAK,GAAG,OAAO,GAAG,cAAc,CAAA;IACtC,yEAAyE;IACzE,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,iCAAiC,CAC/C,oBAA4B,EAC5B,cAAsB;IAEtB,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAA;IACV,CAAC;IACD,2CAA2C;IAC3C,MAAM,OAAO,GAAG,oBAAoB,GAAG,cAAc,CAAA;IACrD,gCAAgC;IAChC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;AAC5B,CAAC"}

package/dist/common/billing/grant-credits.d.ts

@@ -0,0 +1,43 @@
+import { GrantType } from '../db/schema';
+/**
+ * Finds the amount of the most recent expired 'free' grant for a user.
+ * Finds the amount of the most recent expired 'free' grant for a user,
+ * excluding migration grants (operation_id starting with 'migration-').
+ * If there is a previous grant, caps the amount at 2000 credits.
+ * If no expired 'free' grant is found, returns the default free limit.
+ * @param userId The ID of the user.
+ * @returns The amount of the last expired free grant (capped at 2000) or the default.
+ */
+export declare function getPreviousFreeGrantAmount(userId: string): Promise<number>;
+/**
+ * Calculates the total referral bonus credits a user should receive based on
+ * their referral history (both as referrer and referred).
+ * @param userId The ID of the user.
+ * @returns The total referral bonus credits earned.
+ */
+export declare function calculateTotalReferralBonus(userId: string): Promise<number>;
+/**
+ * Processes a credit grant request with retries and failure logging.
+ */
+export declare function processAndGrantCredit(userId: string, amount: number, type: GrantType, description: string, expiresAt: Date | null, operationId: string): Promise<void>;
+/**
+ * Revokes credits from a specific grant by operation ID.
+ * This sets the balance to 0 and updates the description to indicate a refund.
+ *
+ * @param operationId The operation ID of the grant to revoke
+ * @param reason The reason for revoking the credits (e.g. refund)
+ * @returns true if the grant was found and revoked, false otherwise
+ */
+export declare function revokeGrantByOperationId(operationId: string, reason: string): Promise<boolean>;
+/**
+ * Checks if a user's quota needs to be reset, and if so:
+ * 1. Calculates their new monthly grant amount
+ * 2. Issues the grant with the appropriate expiry
+ * 3. Updates their next_quota_reset date
+ * All of this is done in a single transaction with SERIALIZABLE isolation
+ * to prevent concurrent resets from creating duplicate grants.
+ *
+ * @param userId The ID of the user
+ * @returns The effective quota reset date (either existing or new)
+ */
+export declare function triggerMonthlyResetAndGrant(userId: string): Promise<Date>;