codebuff 1.0.219 → 1.0.221

package/dist/common/billing/grant-credits.js

@@ -0,0 +1,201 @@
+"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.getPreviousFreeGrantAmount = getPreviousFreeGrantAmount;
+exports.calculateTotalReferralBonus = calculateTotalReferralBonus;
+exports.processAndGrantCredit = processAndGrantCredit;
+exports.revokeGrantByOperationId = revokeGrantByOperationId;
+const db_1 = __importDefault(require("../db"));
+const schema = __importStar(require("../db/schema"));
+const logger_1 = require("../util/logger");
+const grant_priorities_1 = require("../constants/grant-priorities");
+const drizzle_orm_1 = require("drizzle-orm");
+const constants_1 = require("../constants");
+const promise_1 = require("../util/promise");
+const sync_failure_1 = require("../util/sync-failure");
+/**
+ * Finds the amount of the most recent expired 'free' grant for a user.
+ * 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 or the default.
+ */
+async function getPreviousFreeGrantAmount(userId) {
+    const now = new Date();
+    const lastExpiredFreeGrant = await db_1.default
+        .select({
+        principal: schema.creditLedger.principal,
+    })
+        .from(schema.creditLedger)
+        .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema.creditLedger.user_id, userId), (0, drizzle_orm_1.eq)(schema.creditLedger.type, 'free'), (0, drizzle_orm_1.lte)(schema.creditLedger.expires_at, now) // Grant has expired
+    ))
+        .orderBy((0, drizzle_orm_1.desc)(schema.creditLedger.expires_at)) // Most recent expiry first
+        .limit(1);
+    if (lastExpiredFreeGrant.length > 0) {
+        logger_1.logger.debug({ userId, amount: lastExpiredFreeGrant[0].principal }, 'Found previous expired free grant amount.');
+        return lastExpiredFreeGrant[0].principal;
+    }
+    else {
+        logger_1.logger.debug({ userId, defaultAmount: constants_1.CREDITS_USAGE_LIMITS.FREE }, 'No previous expired free grant found. Using default.');
+        return constants_1.CREDITS_USAGE_LIMITS.FREE; // Default if no previous grant found
+    }
+}
+/**
+ * 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.
+ */
+async function calculateTotalReferralBonus(userId) {
+    try {
+        const result = await db_1.default
+            .select({
+            totalCredits: (0, drizzle_orm_1.sql) `COALESCE(SUM(${schema.referral.credits}), 0)`,
+        })
+            .from(schema.referral)
+            .where((0, drizzle_orm_1.or)((0, drizzle_orm_1.eq)(schema.referral.referrer_id, userId), (0, drizzle_orm_1.eq)(schema.referral.referred_id, userId)));
+        const totalBonus = parseInt(result[0]?.totalCredits ?? '0');
+        logger_1.logger.debug({ userId, totalBonus }, 'Calculated total referral bonus.');
+        return totalBonus;
+    }
+    catch (error) {
+        logger_1.logger.error({ userId, error }, 'Error calculating total referral bonus. Returning 0.');
+        return 0;
+    }
+}
+/**
+ * Core grant operation wrapped in a single DB transaction.
+ */
+async function grantCreditOperation(userId, amount, type, description, expiresAt, operationId) {
+    await db_1.default.transaction(async (tx) => {
+        const now = new Date();
+        // First check for any negative balances
+        const negativeGrants = await tx
+            .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))))
+            .then((grants) => grants.filter((g) => g.balance < 0));
+        if (negativeGrants.length > 0) {
+            const totalDebt = negativeGrants.reduce((sum, g) => sum + Math.abs(g.balance), 0);
+            for (const grant of negativeGrants) {
+                await tx
+                    .update(schema.creditLedger)
+                    .set({ balance: 0 })
+                    .where((0, drizzle_orm_1.eq)(schema.creditLedger.operation_id, grant.operation_id));
+            }
+            const remainingAmount = Math.max(0, amount - totalDebt);
+            if (remainingAmount > 0) {
+                await tx.insert(schema.creditLedger).values({
+                    operation_id: operationId,
+                    user_id: userId,
+                    principal: amount,
+                    balance: remainingAmount,
+                    type,
+                    description: totalDebt > 0
+                        ? `${description} (${totalDebt} credits used to clear existing debt)`
+                        : description,
+                    priority: grant_priorities_1.GRANT_PRIORITIES[type],
+                    expires_at: expiresAt,
+                    created_at: now,
+                });
+            }
+        }
+        else {
+            // No debt - create grant normally
+            await tx.insert(schema.creditLedger).values({
+                operation_id: operationId,
+                user_id: userId,
+                principal: amount,
+                balance: amount,
+                type,
+                description,
+                priority: grant_priorities_1.GRANT_PRIORITIES[type],
+                expires_at: expiresAt,
+                created_at: now,
+            });
+        }
+        logger_1.logger.info({ userId, operationId, type, amount, expiresAt }, 'Created new credit grant');
+    });
+}
+/**
+ * Processes a credit grant request with retries and failure logging.
+ */
+async function processAndGrantCredit(userId, amount, type, description, expiresAt, operationId) {
+    try {
+        await (0, promise_1.withRetry)(() => grantCreditOperation(userId, amount, type, description, expiresAt, operationId), {
+            maxRetries: 3,
+            retryIf: () => true,
+            onRetry: (error, attempt) => {
+                logger_1.logger.warn({ operationId, attempt, error }, `processAndGrantCredit retry ${attempt}`);
+            },
+        });
+    }
+    catch (error) {
+        await (0, sync_failure_1.logSyncFailure)(operationId, error.message, 'internal');
+        logger_1.logger.error({ operationId, error }, 'processAndGrantCredit failed after retries, logged to sync_failure');
+        throw error;
+    }
+}
+/**
+ * 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
+ */
+async function revokeGrantByOperationId(operationId, reason) {
+    return await db_1.default.transaction(async (tx) => {
+        const grant = await tx.query.creditLedger.findFirst({
+            where: (0, drizzle_orm_1.eq)(schema.creditLedger.operation_id, operationId),
+        });
+        if (!grant) {
+            logger_1.logger.warn({ operationId }, 'Attempted to revoke non-existent grant');
+            return false;
+        }
+        if (grant.balance < 0) {
+            logger_1.logger.warn({ operationId, currentBalance: grant.balance }, 'Cannot revoke grant with negative balance - user has already spent these credits');
+            return false;
+        }
+        await tx
+            .update(schema.creditLedger)
+            .set({
+            principal: 0,
+            balance: 0,
+            description: `${grant.description} (Revoked: ${reason})`,
+        })
+            .where((0, drizzle_orm_1.eq)(schema.creditLedger.operation_id, operationId));
+        logger_1.logger.info({
+            operationId,
+            userId: grant.user_id,
+            revokedAmount: grant.balance,
+            reason,
+        }, 'Revoked credit grant');
+        return true;
+    });
+}
+//# sourceMappingURL=grant-credits.js.map

package/dist/common/billing/grant-credits.js.map

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

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

@@ -0,0 +1,13 @@
+import { UsageLimits } from '../constants';
+/**
+ * Determines the user's plan based on their Stripe Price ID.
+ * Defaults to FREE if no matching price ID is found.
+ * NOTE: Requires backend environment variables for Stripe Price IDs.
+ */
+export declare function getPlanFromPriceId(priceId: string | null | undefined, proPriceId?: string, moarProPriceId?: string): UsageLimits;
+/**
+ * Gets the total monthly credit grant amount for a given plan and user.
+ * This includes both their plan's base credits and any referral bonuses,
+ * combined into a single number.
+ */
+export declare function getMonthlyGrantForPlan(plan: UsageLimits, userId?: string): Promise<number>;

package/dist/common/billing/plans.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPlanFromPriceId = getPlanFromPriceId;
+exports.getMonthlyGrantForPlan = getMonthlyGrantForPlan;
+const constants_1 = require("../constants");
+const grant_credits_1 = require("./grant-credits");
+const logger_1 = require("../util/logger");
+/**
+ * Determines the user's plan based on their Stripe Price ID.
+ * Defaults to FREE if no matching price ID is found.
+ * NOTE: Requires backend environment variables for Stripe Price IDs.
+ */
+function getPlanFromPriceId(priceId, proPriceId, moarProPriceId) {
+    if (!priceId) {
+        return constants_1.UsageLimits.FREE;
+    }
+    if (proPriceId && priceId === proPriceId) {
+        return constants_1.UsageLimits.PRO;
+    }
+    if (moarProPriceId && priceId === moarProPriceId) {
+        return constants_1.UsageLimits.MOAR_PRO;
+    }
+    return constants_1.UsageLimits.FREE; // Default to FREE for unknown or non-matching IDs
+}
+/**
+ * Gets the total monthly credit grant amount for a given plan and user.
+ * This includes both their plan's base credits and any referral bonuses,
+ * combined into a single number.
+ */
+async function getMonthlyGrantForPlan(plan, userId) {
+    // If no userId provided, just return the plan's base limit
+    if (!userId) {
+        return constants_1.PLAN_CONFIGS[plan]?.limit ?? constants_1.PLAN_CONFIGS[constants_1.UsageLimits.FREE].limit;
+    }
+    // Calculate total grant by adding base plan amount and referral bonuses
+    const [freeGrantAmount, referralBonus] = await Promise.all([
+        (0, grant_credits_1.getPreviousFreeGrantAmount)(userId),
+        (0, grant_credits_1.calculateTotalReferralBonus)(userId),
+    ]);
+    const totalGrant = freeGrantAmount + referralBonus;
+    logger_1.logger.debug({ userId, plan, freeGrantAmount, referralBonus, totalGrant }, 'Calculated total monthly grant amount');
+    return totalGrant;
+}
+//# sourceMappingURL=plans.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plans.js","sourceRoot":"","sources":["../../src/billing/plans.ts"],"names":[],"mappings":";;AASA,gDAiBC;AAOD,wDAqBC;AAtDD,4CAAwD;AACxD,mDAAyF;AACzF,2CAAuC;AAEvC;;;;GAIG;AACH,SAAgB,kBAAkB,CAChC,OAAkC,EAClC,UAAmB,EACnB,cAAuB;IAEvB,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,uBAAW,CAAC,IAAI,CAAA;IACzB,CAAC;IAED,IAAI,UAAU,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QACzC,OAAO,uBAAW,CAAC,GAAG,CAAA;IACxB,CAAC;IACD,IAAI,cAAc,IAAI,OAAO,KAAK,cAAc,EAAE,CAAC;QACjD,OAAO,uBAAW,CAAC,QAAQ,CAAA;IAC7B,CAAC;IAED,OAAO,uBAAW,CAAC,IAAI,CAAA,CAAC,kDAAkD;AAC5E,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,sBAAsB,CAC1C,IAAiB,EACjB,MAAe;IAEf,2DAA2D;IAC3D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,wBAAY,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,wBAAY,CAAC,uBAAW,CAAC,IAAI,CAAC,CAAC,KAAK,CAAA;IAC1E,CAAC;IAED,wEAAwE;IACxE,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACzD,IAAA,0CAA0B,EAAC,MAAM,CAAC;QAClC,IAAA,2CAA2B,EAAC,MAAM,CAAC;KACpC,CAAC,CAAA;IAEF,MAAM,UAAU,GAAG,eAAe,GAAG,aAAa,CAAA;IAClD,eAAM,CAAC,KAAK,CACV,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,EAC5D,uCAAuC,CACxC,CAAA;IACD,OAAO,UAAU,CAAA;AACnB,CAAC"}

package/dist/common/billing/rollover-logic.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Calculates the rollover amount for a user at the end of their billing cycle
+ * and applies the necessary database updates (creates rollover grant, resets usage, updates reset date).
+ *
+ * NOTE: This function performs database writes and should be called within a transaction
+ * if invoked alongside other database operations. It also depends on the `credit_grants`
+ * table and the modified `user` table schema being in place.
+ *
+ * @param userId The ID of the user whose cycle is ending.
+ * @param cycleEndDate The exact date and time the billing cycle ended.
+ * @returns A Promise resolving when the process is complete.
+ */
+export declare function calculateAndApplyRollover(userId: string, cycleEndDate: Date): Promise<void>;

package/dist/common/billing/rollover-logic.js

@@ -0,0 +1,174 @@
+"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.calculateAndApplyRollover = calculateAndApplyRollover;
+const db_1 = __importDefault(require("../db"));
+const schema = __importStar(require("../db/schema"));
+const drizzle_orm_1 = require("drizzle-orm");
+const balance_calculator_1 = require("./balance-calculator");
+const logger_1 = require("../util/logger");
+const dates_1 = require("../util/dates"); // Assuming this utility exists/is created
+// Define which grant types contribute to rollover
+const ROLLOVER_GRANT_TYPES = ['purchase', 'rollover'];
+/**
+ * Calculates the rollover amount for a user at the end of their billing cycle
+ * and applies the necessary database updates (creates rollover grant, resets usage, updates reset date).
+ *
+ * NOTE: This function performs database writes and should be called within a transaction
+ * if invoked alongside other database operations. It also depends on the `credit_grants`
+ * table and the modified `user` table schema being in place.
+ *
+ * @param userId The ID of the user whose cycle is ending.
+ * @param cycleEndDate The exact date and time the billing cycle ended.
+ * @returns A Promise resolving when the process is complete.
+ */
+async function calculateAndApplyRollover(userId, cycleEndDate) {
+    logger_1.logger.info({ userId, cycleEndDate }, 'Starting end-of-cycle rollover process');
+    try {
+        // 1. Fetch the user's usage for the cycle that just ended
+        // We need the user record to get the usage *before* resetting it.
+        const user = await db_1.default.query.user.findFirst({
+            where: (0, drizzle_orm_1.eq)(schema.user.id, userId),
+            columns: { usage: true, next_quota_reset: true }, // Also get current reset date
+        });
+        if (!user) {
+            logger_1.logger.error({ userId }, 'User not found during rollover calculation.');
+            return;
+        }
+        // Ensure we don't run rollover multiple times for the same cycle
+        if (user.next_quota_reset && user.next_quota_reset > cycleEndDate) {
+            logger_1.logger.warn({ userId, cycleEndDate, nextReset: user.next_quota_reset }, 'Rollover attempted for a cycle that has not yet ended or already processed. Skipping.');
+            return;
+        }
+        const endedCycleUsage = user.usage;
+        // Calculate the start date of the ended cycle (approximate)
+        const cycleStartDate = new Date(cycleEndDate);
+        cycleStartDate.setMonth(cycleStartDate.getMonth() - 1); // Approximation
+        // 2. Fetch all grants that were active *during* the ended cycle
+        // Active during cycle: created_at < cycleEndDate AND (expires_at IS NULL OR expires_at > cycleStartDate)
+        const grantsActiveDuringCycle = await db_1.default
+            .select()
+            .from(schema.creditGrants)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema.creditGrants.user_id, userId), (0, drizzle_orm_1.lte)(schema.creditGrants.created_at, cycleEndDate), // Created before or exactly at cycle end
+        (0, drizzle_orm_1.or)((0, drizzle_orm_1.isNull)(schema.creditGrants.expires_at), // Never expires
+        (0, drizzle_orm_1.gt)(schema.creditGrants.expires_at, cycleStartDate) // Expired after cycle start
+        )))
+            // 3. Order grants by priority ASC, then created_at ASC
+            .orderBy((0, drizzle_orm_1.asc)(schema.creditGrants.priority), (0, drizzle_orm_1.asc)(schema.creditGrants.created_at));
+        // 4. Initialize rollover amount
+        let rolloverAmount = 0;
+        // 5. Initialize usage to account for from the ended cycle
+        let usageToAccountFor = endedCycleUsage;
+        logger_1.logger.debug({ userId, endedCycleUsage, grantsCount: grantsActiveDuringCycle.length }, 'Simulating consumption for ended cycle');
+        // 6. Simulate Cycle Consumption
+        for (const grant of grantsActiveDuringCycle) {
+            const consumedFromThisGrant = Math.min(grant.amount, usageToAccountFor);
+            const remainingInThisGrant = grant.amount - consumedFromThisGrant;
+            usageToAccountFor -= consumedFromThisGrant;
+            logger_1.logger.trace({
+                userId,
+                grantId: grant.operation_id,
+                grantType: grant.type,
+                grantAmount: grant.amount,
+                consumed: consumedFromThisGrant,
+                remainingInGrant: remainingInThisGrant,
+                usageLeftToAccount: usageToAccountFor,
+            }, 'Processing grant during rollover simulation');
+            // 7. Check for Rollover Contribution
+            if (remainingInThisGrant > 0 &&
+                ROLLOVER_GRANT_TYPES.includes(grant.type)) {
+                rolloverAmount += remainingInThisGrant;
+                logger_1.logger.trace({
+                    userId,
+                    grantId: grant.operation_id,
+                    addedToRollover: remainingInThisGrant,
+                    newTotalRollover: rolloverAmount,
+                }, 'Grant contributed to rollover amount');
+            }
+            if (usageToAccountFor <= 0) {
+                // If usage is covered, check remaining grants for rollover contributions
+                const remainingGrants = grantsActiveDuringCycle.slice(grantsActiveDuringCycle.indexOf(grant) + 1);
+                for (const remainingGrant of remainingGrants) {
+                    if (ROLLOVER_GRANT_TYPES.includes(remainingGrant.type)) {
+                        rolloverAmount += remainingGrant.amount;
+                        logger_1.logger.trace({
+                            userId,
+                            grantId: remainingGrant.operation_id,
+                            addedToRollover: remainingGrant.amount,
+                            newTotalRollover: rolloverAmount,
+                        }, 'Untouched grant contributed to rollover amount');
+                    }
+                }
+                break; // All usage accounted for
+            }
+        }
+        logger_1.logger.info({ userId, endedCycleUsage, calculatedRollover: rolloverAmount }, 'Rollover calculation complete');
+        // 8. Database Updates (Perform as a transaction)
+        await db_1.default.transaction(async (tx) => {
+            // Insert new 'rollover' grant if amount > 0
+            if (rolloverAmount > 0) {
+                const rolloverGrantId = `rollover-${userId}-${cycleEndDate.toISOString()}`;
+                await tx
+                    .insert(schema.creditGrants)
+                    .values({
+                    operation_id: rolloverGrantId,
+                    user_id: userId,
+                    amount: rolloverAmount,
+                    amount_remaining: rolloverAmount, // Initialize amount_remaining to the full amount
+                    type: 'rollover', // Use string literal directly
+                    priority: balance_calculator_1.GRANT_PRIORITIES.rollover, // Use defined priority
+                    expires_at: null, // Rollover credits don't expire
+                    description: `Rollover from cycle ending ${cycleEndDate.toLocaleDateString()}`,
+                    // stripe_grant_id is NULL for local grants
+                })
+                    .onConflictDoNothing(); // Avoid duplicate rollovers if run concurrently
+                logger_1.logger.debug({ userId, rolloverAmount }, 'Inserted rollover grant');
+            }
+            else {
+                logger_1.logger.debug({ userId }, 'No rollover amount to grant.');
+            }
+            // Update the user: reset usage and set next reset date
+            const nextResetDate = (0, dates_1.getNextQuotaReset)(cycleEndDate); // Calculate the next reset date based on the cycle end
+            await tx
+                .update(schema.user)
+                .set({
+                usage: 0,
+                next_quota_reset: nextResetDate,
+            })
+                .where((0, drizzle_orm_1.eq)(schema.user.id, userId));
+            logger_1.logger.info({ userId, nextResetDate: nextResetDate.toISOString() }, 'User usage reset and next reset date updated');
+        });
+        logger_1.logger.info({ userId }, 'Rollover process completed successfully.');
+    }
+    catch (error) {
+        logger_1.logger.error({ userId, cycleEndDate, error }, 'Error during rollover process');
+        // Depending on trigger mechanism, might need error handling/retry logic here
+        throw error; // Re-throw to indicate failure if called from a job
+    }
+}
+//# sourceMappingURL=rollover-logic.js.map

package/dist/common/billing/rollover-logic.js.map

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

package/dist/common/billing/stripe-api.d.ts

@@ -0,0 +1,31 @@
+import { CreditType } from './balance-calculator';
+import Stripe from 'stripe';
+export declare const stripeApi: {
+    credits: {
+        /**
+         * Creates a customer balance transaction in Stripe to grant credits.
+         * NOTE: Database insertion for a local 'creditGrant' record is commented out
+         * as the 'creditGrant' table doesn't exist in the current schema.
+         */
+        create({ userId, amount, type, expiresAt, description, metadata }: {
+            userId: string;
+            amount: number;
+            type: CreditType;
+            expiresAt?: Date;
+            description?: string;
+            metadata?: Record<string, string | number | null>;
+        }): Promise<Stripe.CustomerBalanceTransaction>;
+        /**
+         * Retrieves the customer's cash balance from Stripe.
+         * Note: This is the overall cash balance, typically negative if credits have been granted.
+         * It does NOT represent the sum of specific "credit grants".
+         */
+        getBalance(userId: string): Promise<number>;
+    };
+    usage: {
+        /**
+         * Reports usage to a Stripe meter.
+         */
+        report(userId: string, amount: number, metadata?: Record<string, any>): Promise<Stripe.Response<Stripe.Billing.MeterEvent>>;
+    };
+};

package/dist/common/billing/stripe-api.js

@@ -0,0 +1,104 @@
+"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.stripeApi = void 0;
+const db_1 = __importDefault(require("../db"));
+const schema = __importStar(require("../db/schema"));
+const drizzle_orm_1 = require("drizzle-orm");
+const stripe_1 = require("../util/stripe");
+const balance_calculator_1 = require("./balance-calculator");
+// Helper to get Stripe Customer ID
+async function getCustomerId(userId) {
+    const user = await db_1.default.query.user.findFirst({
+        where: (0, drizzle_orm_1.eq)(schema.user.id, userId),
+        columns: { stripe_customer_id: true }
+    });
+    if (!user?.stripe_customer_id) {
+        throw new Error(`Stripe customer ID not found for user ${userId}`);
+    }
+    return user.stripe_customer_id;
+}
+exports.stripeApi = {
+    credits: {
+        /**
+         * Creates a customer balance transaction in Stripe to grant credits.
+         * NOTE: Database insertion for a local 'creditGrant' record is commented out
+         * as the 'creditGrant' table doesn't exist in the current schema.
+         */
+        async create({ userId, amount, type, expiresAt, description, metadata = {} }) {
+            const customerId = await getCustomerId(userId);
+            const priority = balance_calculator_1.CREDIT_PRIORITIES[type];
+            const amountInCents = -Math.abs(amount);
+            const transaction = await stripe_1.stripeServer.customers.createBalanceTransaction(customerId, {
+                amount: amountInCents,
+                currency: 'usd',
+                description: description ?? `${type} credits granted`,
+                metadata: {
+                    ...metadata,
+                    type: type,
+                    priority: priority.toString(),
+                }
+            });
+            return transaction;
+        },
+        /**
+         * Retrieves the customer's cash balance from Stripe.
+         * Note: This is the overall cash balance, typically negative if credits have been granted.
+         * It does NOT represent the sum of specific "credit grants".
+         */
+        async getBalance(userId) {
+            const customerId = await getCustomerId(userId);
+            const customer = await stripe_1.stripeServer.customers.retrieve(customerId);
+            if (customer.deleted) {
+                return 0;
+            }
+            return customer.balance ?? 0;
+        }
+    },
+    usage: {
+        /**
+         * Reports usage to a Stripe meter.
+         */
+        async report(userId, amount, metadata = {}) {
+            const customerId = await getCustomerId(userId);
+            const eventName = 'codebuff_credits_used';
+            return stripe_1.stripeServer.billing.meterEvents.create({
+                event_name: eventName,
+                timestamp: Math.floor(Date.now() / 1000),
+                payload: {
+                    stripe_customer_id: customerId,
+                    value: amount.toString(),
+                    ...metadata
+                }
+            }).catch((err) => {
+                throw err;
+            });
+        }
+    }
+};
+//# sourceMappingURL=stripe-api.js.map

package/dist/common/billing/stripe-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe-api.js","sourceRoot":"","sources":["../../src/billing/stripe-api.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,+CAAsB;AACtB,qDAAsC;AACtC,6CAAgC;AAChC,2CAA6C;AAC7C,6DAAoE;AAGpE,mCAAmC;AACnC,KAAK,UAAU,aAAa,CAAC,MAAc;IACvC,MAAM,IAAI,GAAG,MAAM,YAAE,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;QACvC,KAAK,EAAE,IAAA,gBAAE,EAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC;QACjC,OAAO,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE;KACxC,CAAC,CAAC;IACH,IAAI,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yCAAyC,MAAM,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,IAAI,CAAC,kBAAkB,CAAC;AACnC,CAAC;AAEY,QAAA,SAAS,GAAG;IACvB,OAAO,EAAE;QACP;;;;WAIG;QACH,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,GAAG,EAAE,EAOzE;YACC,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAA;YAC9C,MAAM,QAAQ,GAAG,sCAAiB,CAAC,IAAI,CAAC,CAAA;YAExC,MAAM,aAAa,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAExC,MAAM,WAAW,GAAG,MAAM,qBAAY,CAAC,SAAS,CAAC,wBAAwB,CACrE,UAAU,EACV;gBACI,MAAM,EAAE,aAAa;gBACrB,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,WAAW,IAAI,GAAG,IAAI,kBAAkB;gBACrD,QAAQ,EAAE;oBACN,GAAG,QAAQ;oBACX,IAAI,EAAE,IAAI;oBACV,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE;iBAChC;aACJ,CACJ,CAAC;YAEF,OAAO,WAAW,CAAA;QACpB,CAAC;QAED;;;;WAIG;QACH,KAAK,CAAC,UAAU,CAAC,MAAc;YAC3B,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;YAC/C,MAAM,QAAQ,GAAG,MAAM,qBAAY,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YAEnE,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACnB,OAAO,CAAC,CAAC;YACb,CAAC;YAED,OAAO,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;QACjC,CAAC;KACF;IACD,KAAK,EAAE;QACL;;WAEG;QACH,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,MAAc,EAAE,WAAgC,EAAE;YAC7E,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,CAAA;YAC9C,MAAM,SAAS,GAAG,uBAAuB,CAAC;YAE1C,OAAO,qBAAY,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC;gBAC7C,UAAU,EAAE,SAAS;gBACrB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;gBACxC,OAAO,EAAE;oBACP,kBAAkB,EAAE,UAAU;oBAC9B,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE;oBACxB,GAAG,QAAQ;iBACZ;aACF,CAAC,CAAC,KAAK,CAAC,CAAC,GAAU,EAAE,EAAE;gBACpB,MAAM,GAAG,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC;KACF;CACF,CAAA"}