codebuff 1.0.224 → 1.0.225

package/dist/common/advanced-analyzer.d.ts

@@ -0,0 +1,19 @@
+import { BrowserResponse } from './browser-actions';
+/**
+ * Each detected issue includes a type, severity, detection reason,
+ * and an optional recommendation for the user.
+ */
+export interface AnalysisIssue {
+    type: string;
+    severity: 'low' | 'medium' | 'high';
+    message: string;
+    recommendation?: string;
+}
+export interface AnalysisResult {
+    issues: AnalysisIssue[];
+}
+/**
+ * Entrypoint function to run a suite of heuristic checks over
+ * logs, network events, performance metrics, etc.
+ */
+export declare function analyzeBrowserData(response: BrowserResponse): AnalysisResult;

package/dist/common/advanced-analyzer.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeBrowserData = analyzeBrowserData;
+/**
+ * Entrypoint function to run a suite of heuristic checks over
+ * logs, network events, performance metrics, etc.
+ */
+function analyzeBrowserData(response) {
+    const issues = [];
+    // 1. Check logs for known error patterns or repeated errors
+    issues.push(...analyzeLogs(response));
+    // 2. Check network events for 4xx, 5xx, or suspicious patterns
+    issues.push(...analyzeNetwork(response));
+    // 3. Check performance metrics (TTFB, LCP, memory usage, etc.)
+    if (response.metrics) {
+        issues.push(...analyzePerformance(response.metrics));
+    }
+    // Return combined issues
+    return { issues };
+}
+function analyzeLogs(response) {
+    const issues = [];
+    const logs = response.logs || [];
+    // Check for high number of JavaScript errors
+    const jsErrors = logs.filter((log) => log.type === 'error');
+    if (jsErrors.length > 5) {
+        issues.push({
+            type: 'JS_ERROR_OVERFLOW',
+            severity: 'medium',
+            message: `Detected ${jsErrors.length} JavaScript errors in logs.`,
+            recommendation: 'Review the console logs for repeated error patterns. Fix the root cause or handle errors in code.'
+        });
+    }
+    // Pattern-based error detection
+    const errorPatterns = {
+        'not defined': {
+            severity: 'medium',
+            recommendation: 'Check for missing script dependencies or undefined variables'
+        },
+        'Failed to fetch': {
+            severity: 'medium',
+            recommendation: 'Verify endpoint URLs and network connectivity'
+        },
+        'SSL': {
+            severity: 'high',
+            recommendation: 'SSL certificate error - check HTTPS configuration'
+        },
+        'ERR_NAME_NOT_RESOLVED': {
+            severity: 'medium',
+            recommendation: 'DNS resolution failed - check domain name'
+        },
+        'ERR_CONNECTION_TIMED_OUT': {
+            severity: 'medium',
+            recommendation: 'Connection timeout - check network or firewall'
+        },
+        'Navigation timeout': {
+            severity: 'medium',
+            recommendation: 'Page took too long to load - check performance or timeouts'
+        },
+        'Frame detached': {
+            severity: 'low',
+            recommendation: 'Target frame or element no longer exists'
+        },
+        'Node is detached': {
+            severity: 'low',
+            recommendation: 'Element was removed from DOM'
+        }
+    };
+    for (const log of jsErrors) {
+        for (const [pattern, { severity, recommendation }] of Object.entries(errorPatterns)) {
+            if (log.message.includes(pattern)) {
+                issues.push({
+                    type: 'JS_ERROR',
+                    severity,
+                    message: `Error detected: ${log.message}`,
+                    recommendation
+                });
+                break; // Stop after first matching pattern
+            }
+        }
+    }
+    return issues;
+}
+function analyzeNetwork(response) {
+    const issues = [];
+    const netEvents = response.networkEvents || [];
+    // Count 4xx / 5xx
+    const errorEvents = netEvents.filter((evt) => (evt.status && evt.status >= 400) || evt.errorText);
+    if (errorEvents.length > 0) {
+        issues.push({
+            type: 'NETWORK_ERRORS',
+            severity: 'medium',
+            message: `${errorEvents.length} network request(s) failed with 4xx/5xx error(s).`,
+            recommendation: 'Check your API endpoints and resource URLs. Verify server logs for possible configuration or routing issues.'
+        });
+    }
+    // Detect repeated 404s
+    const fourOhFours = netEvents.filter((e) => e.status === 404);
+    if (fourOhFours.length > 2) {
+        issues.push({
+            type: 'MISSING_RESOURCES',
+            severity: 'low',
+            message: `${fourOhFours.length} resources returned 404 Not Found.`,
+            recommendation: 'Ensure static assets or pages exist at the requested path.'
+        });
+    }
+    return issues;
+}
+function analyzePerformance(metrics) {
+    const issues = [];
+    // Check Time to First Byte
+    if ((metrics.ttfb ?? 0) > 1000) {
+        issues.push({
+            type: 'HIGH_TTFB',
+            severity: 'medium',
+            message: `Time to First Byte is ${metrics.ttfb}ms, which is high.`,
+            recommendation: 'Optimize server response times or check network constraints. Look for server-side bottlenecks.'
+        });
+    }
+    // Check memory usage
+    if (metrics.memoryUsage > 100_000_000) { // ~100MB in JS heap
+        issues.push({
+            type: 'HIGH_MEMORY_USAGE',
+            severity: 'medium',
+            message: `Memory usage reached ${metrics.memoryUsage} bytes in JS heap.`,
+            recommendation: 'Investigate potential memory leaks, unbounded data structures, or large on-page assets.'
+        });
+    }
+    // Check Largest Contentful Paint
+    if ((metrics.lcp ?? 0) > 4000) {
+        issues.push({
+            type: 'PERFORMANCE_LCP',
+            severity: 'medium',
+            message: `Largest Contentful Paint is ${metrics.lcp}ms (over 4s).`,
+            recommendation: 'Consider optimizing images, breaking up large bundle files, or deferring non-critical scripts.'
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=advanced-analyzer.js.map

package/dist/common/advanced-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced-analyzer.js","sourceRoot":"","sources":["../src/advanced-analyzer.ts"],"names":[],"mappings":";;AAqBA,gDAgBC;AApBD;;;GAGG;AACH,SAAgB,kBAAkB,CAAC,QAAyB;IAC1D,MAAM,MAAM,GAAoB,EAAE,CAAA;IAElC,4DAA4D;IAC5D,MAAM,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAA;IAErC,+DAA+D;IAC/D,MAAM,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAA;IAExC,+DAA+D;IAC/D,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAA;IACtD,CAAC;IAED,yBAAyB;IACzB,OAAO,EAAE,MAAM,EAAE,CAAA;AACnB,CAAC;AAED,SAAS,WAAW,CAAC,QAAyB;IAC5C,MAAM,MAAM,GAAoB,EAAE,CAAA;IAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAA;IAEhC,6CAA6C;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,OAAO,CAAC,CAAA;IAC3D,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,mBAAmB;YACzB,QAAQ,EAAE,QAAQ;YAClB,OAAO,EAAE,YAAY,QAAQ,CAAC,MAAM,6BAA6B;YACjE,cAAc,EACZ,mGAAmG;SACtG,CAAC,CAAA;IACJ,CAAC;IAED,gCAAgC;IAChC,MAAM,aAAa,GAAoF;QACrG,aAAa,EAAE;YACb,QAAQ,EAAE,QAAQ;YAClB,cAAc,EAAE,8DAA8D;SAC/E;QACD,iBAAiB,EAAE;YACjB,QAAQ,EAAE,QAAQ;YAClB,cAAc,EAAE,+CAA+C;SAChE;QACD,KAAK,EAAE;YACL,QAAQ,EAAE,MAAM;YAChB,cAAc,EAAE,mDAAmD;SACpE;QACD,uBAAuB,EAAE;YACvB,QAAQ,EAAE,QAAQ;YAClB,cAAc,EAAE,2CAA2C;SAC5D;QACD,0BAA0B,EAAE;YAC1B,QAAQ,EAAE,QAAQ;YAClB,cAAc,EAAE,gDAAgD;SACjE;QACD,oBAAoB,EAAE;YACpB,QAAQ,EAAE,QAAQ;YAClB,cAAc,EAAE,4DAA4D;SAC7E;QACD,gBAAgB,EAAE;YAChB,QAAQ,EAAE,KAAK;YACf,cAAc,EAAE,0CAA0C;SAC3D;QACD,kBAAkB,EAAE;YAClB,QAAQ,EAAE,KAAK;YACf,cAAc,EAAE,8BAA8B;SAC/C;KACF,CAAA;IAED,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;YACpF,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBAClC,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,UAAU;oBAChB,QAAQ;oBACR,OAAO,EAAE,mBAAmB,GAAG,CAAC,OAAO,EAAE;oBACzC,cAAc;iBACf,CAAC,CAAA;gBACF,MAAK,CAAC,oCAAoC;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,cAAc,CAAC,QAAyB;IAC/C,MAAM,MAAM,GAAoB,EAAE,CAAA;IAClC,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,IAAI,EAAE,CAAA;IAE9C,kBAAkB;IAClB,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,CAClC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,SAAS,CAC5D,CAAA;IACD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,gBAAgB;YACtB,QAAQ,EAAE,QAAQ;YAClB,OAAO,EAAE,GAAG,WAAW,CAAC,MAAM,mDAAmD;YACjF,cAAc,EACZ,8GAA8G;SACjH,CAAC,CAAA;IACJ,CAAC;IAED,uBAAuB;IACvB,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,CAAA;IAC7D,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,mBAAmB;YACzB,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,GAAG,WAAW,CAAC,MAAM,oCAAoC;YAClE,cAAc,EAAE,4DAA4D;SAC7E,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,OAA6C;IACvE,MAAM,MAAM,GAAoB,EAAE,CAAA;IAElC,2BAA2B;IAC3B,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,WAAW;YACjB,QAAQ,EAAE,QAAQ;YAClB,OAAO,EAAE,yBAAyB,OAAO,CAAC,IAAI,oBAAoB;YAClE,cAAc,EACZ,gGAAgG;SACnG,CAAC,CAAA;IACJ,CAAC;IAED,qBAAqB;IACrB,IAAI,OAAO,CAAC,WAAW,GAAG,WAAW,EAAE,CAAC,CAAC,oBAAoB;QAC3D,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,mBAAmB;YACzB,QAAQ,EAAE,QAAQ;YAClB,OAAO,EAAE,wBAAwB,OAAO,CAAC,WAAW,oBAAoB;YACxE,cAAc,EACZ,yFAAyF;SAC5F,CAAC,CAAA;IACJ,CAAC;IAED,iCAAiC;IACjC,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,iBAAiB;YACvB,QAAQ,EAAE,QAAQ;YAClB,OAAO,EAAE,+BAA+B,OAAO,CAAC,GAAG,eAAe;YAClE,cAAc,EACZ,gGAAgG;SACnG,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

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

@@ -21,8 +21,8 @@ type DbConn = Pick<typeof db, 'select' | 'update'>;
  * 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<{
-    type: import("../types/grant").GrantType;
     created_at: Date;
+    type: import("../types/grant").GrantType;
     expires_at: Date | null;
     operation_id: string;
     user_id: string;

package/dist/common/billing/check-auto-topup.d.ts

@@ -0,0 +1,12 @@
+import type Stripe from 'stripe';
+export interface AutoTopupCheckResult {
+    blockedReason: string | null;
+    validPaymentMethod: Stripe.PaymentMethod | null;
+}
+/**
+ * Checks if auto top-up is allowed for a user by verifying their payment methods.
+ * @param userId The ID of the user for logging context
+ * @param stripeCustomerId The user's Stripe customer ID
+ * @returns Promise<AutoTopupCheckResult>
+ */
+export declare function checkAutoTopupAllowed(userId: string, stripeCustomerId: string | null): Promise<AutoTopupCheckResult>;

package/dist/common/billing/check-auto-topup.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkAutoTopupAllowed = checkAutoTopupAllowed;
+const stripe_1 = require("../util/stripe");
+const logger_1 = require("../util/logger");
+const env_mjs_1 = require("src/env.mjs");
+/**
+ * Checks if auto top-up is allowed for a user by verifying their payment methods.
+ * @param userId The ID of the user for logging context
+ * @param stripeCustomerId The user's Stripe customer ID
+ * @returns Promise<AutoTopupCheckResult>
+ */
+async function checkAutoTopupAllowed(userId, stripeCustomerId) {
+    const logContext = { userId };
+    if (!stripeCustomerId) {
+        return {
+            blockedReason: `You don\'t have a valid account with us. Please log in at ${env_mjs_1.env.NEXT_PUBLIC_APP_URL}/login`,
+            validPaymentMethod: null,
+        };
+    }
+    try {
+        const paymentMethods = await stripe_1.stripeServer.paymentMethods.list({
+            customer: stripeCustomerId,
+            type: 'card',
+        });
+        // Find a valid, non-expired card
+        const validPaymentMethod = paymentMethods.data.find((pm) => pm.card?.exp_year &&
+            pm.card.exp_month &&
+            new Date(pm.card.exp_year, pm.card.exp_month - 1) > new Date());
+        if (!validPaymentMethod) {
+            logger_1.logger.warn({ ...logContext }, 'No valid payment methods found for auto top-up');
+            return {
+                blockedReason: 'You need a valid payment method to enable auto top-up. You can add one by manually purchasing credits.',
+                validPaymentMethod: null,
+            };
+        }
+        return {
+            blockedReason: null,
+            validPaymentMethod,
+        };
+    }
+    catch (error) {
+        logger_1.logger.error({ ...logContext, error }, 'Failed to fetch payment methods');
+        return {
+            blockedReason: 'Unable to verify payment method status.',
+            validPaymentMethod: null,
+        };
+    }
+}
+//# sourceMappingURL=check-auto-topup.js.map

package/dist/common/billing/check-auto-topup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-auto-topup.js","sourceRoot":"","sources":["../../src/billing/check-auto-topup.ts"],"names":[],"mappings":";;AAgBA,sDAkDC;AAlED,2CAA6C;AAC7C,2CAAuC;AAEvC,yCAAiC;AAOjC;;;;;GAKG;AACI,KAAK,UAAU,qBAAqB,CACzC,MAAc,EACd,gBAA+B;IAE/B,MAAM,UAAU,GAAG,EAAE,MAAM,EAAE,CAAA;IAE7B,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,OAAO;YACL,aAAa,EAAE,6DAA6D,aAAG,CAAC,mBAAmB,QAAQ;YAC3G,kBAAkB,EAAE,IAAI;SACzB,CAAA;IACH,CAAC;IAED,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,MAAM,qBAAY,CAAC,cAAc,CAAC,IAAI,CAAC;YAC5D,QAAQ,EAAE,gBAAgB;YAC1B,IAAI,EAAE,MAAM;SACb,CAAC,CAAA;QAEF,iCAAiC;QACjC,MAAM,kBAAkB,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CACjD,CAAC,EAAE,EAAE,EAAE,CACL,EAAE,CAAC,IAAI,EAAE,QAAQ;YACjB,EAAE,CAAC,IAAI,CAAC,SAAS;YACjB,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,IAAI,IAAI,EAAE,CACjE,CAAA;QAED,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACxB,eAAM,CAAC,IAAI,CACT,EAAE,GAAG,UAAU,EAAE,EACjB,gDAAgD,CACjD,CAAA;YACD,OAAO;gBACL,aAAa,EACX,wGAAwG;gBAC1G,kBAAkB,EAAE,IAAI;aACzB,CAAA;QACH,CAAC;QAED,OAAO;YACL,aAAa,EAAE,IAAI;YACnB,kBAAkB;SACnB,CAAA;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,eAAM,CAAC,KAAK,CAAC,EAAE,GAAG,UAAU,EAAE,KAAK,EAAE,EAAE,iCAAiC,CAAC,CAAA;QACzE,OAAO;YACL,aAAa,EAAE,yCAAyC;YACxD,kBAAkB,EAAE,IAAI;SACzB,CAAA;IACH,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,8 @@
+import { CreditBalance } from './balance-calculator';
+/**
+ * Gets the current detailed credit balance for a user.
+ * Returns a zero balance for anonymous users.
+ * @param userId The ID of the user, or undefined for anonymous.
+ * @returns A Promise resolving to the user's CreditBalance.
+ */
+export declare function getCurrentBalanceDetails(userId: string | undefined): Promise<CreditBalance>;

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

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentBalanceDetails = getCurrentBalanceDetails;
+const balance_calculator_1 = require("./balance-calculator");
+const logger_1 = require("../util/logger");
+/**
+ * Gets the current detailed credit balance for a user.
+ * Returns a zero balance for anonymous users.
+ * @param userId The ID of the user, or undefined for anonymous.
+ * @returns A Promise resolving to the user's CreditBalance.
+ */
+async function getCurrentBalanceDetails(userId) {
+    if (!userId) {
+        // Return zero/default balance for anonymous users
+        return {
+            totalRemaining: 0,
+            breakdown: {
+                free: 0,
+                referral: 0,
+                purchase: 0,
+                admin: 0,
+                rollover: 0,
+            },
+        };
+    }
+    try {
+        // Use the new balance calculation logic
+        return await (0, balance_calculator_1.calculateCurrentBalance)(userId);
+    }
+    catch (error) {
+        logger_1.logger.error({ userId, error }, 'Error fetching balance details');
+        // Return a zero balance on error
+        return {
+            totalRemaining: 0,
+            breakdown: {
+                free: 0,
+                referral: 0,
+                purchase: 0,
+                admin: 0,
+                rollover: 0,
+            },
+        };
+    }
+}
+//# sourceMappingURL=credit-check.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credit-check.js","sourceRoot":"","sources":["../../src/billing/credit-check.ts"],"names":[],"mappings":";;AASA,4DAkCC;AA3CD,6DAA6E;AAC7E,2CAAuC;AAEvC;;;;;GAKG;AACI,KAAK,UAAU,wBAAwB,CAC5C,MAA0B;IAE1B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,kDAAkD;QAClD,OAAO;YACL,cAAc,EAAE,CAAC;YACjB,SAAS,EAAE;gBACT,IAAI,EAAE,CAAC;gBACP,QAAQ,EAAE,CAAC;gBACX,QAAQ,EAAE,CAAC;gBACX,KAAK,EAAE,CAAC;gBACR,QAAQ,EAAE,CAAC;aACZ;SACF,CAAA;IACH,CAAC;IAED,IAAI,CAAC;QACH,wCAAwC;QACxC,OAAO,MAAM,IAAA,4CAAuB,EAAC,MAAM,CAAC,CAAA;IAC9C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,eAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,gCAAgC,CAAC,CAAA;QACjE,iCAAiC;QACjC,OAAO;YACL,cAAc,EAAE,CAAC;YACjB,SAAS,EAAE;gBACT,IAAI,EAAE,CAAC;gBACP,QAAQ,EAAE,CAAC;gBACX,QAAQ,EAAE,CAAC;gBACX,KAAK,EAAE,CAAC;gBACR,QAAQ,EAAE,CAAC;aACZ;SACF,CAAA;IACH,CAAC;AACH,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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuBA,8DAsLC;AA7MD,+CAAsB;AACtB,qDAAsC;AACtC,6CAAoE;AACpE,6DAAuD;AACvD,2CAAuC;AACvC,yCAAiD,CAAC,0CAA0C;AAG5F,kDAAkD;AAClD,MAAM,oBAAoB,GAAgB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;AAElE;;;;;;;;;;;GAWG;AACI,KAAK,UAAU,yBAAyB,CAC7C,MAAc,EACd,YAAkB;IAElB,eAAM,CAAC,IAAI,CACT,EAAE,MAAM,EAAE,YAAY,EAAE,EACxB,wCAAwC,CACzC,CAAA;IAED,IAAI,CAAC;QACH,0DAA0D;QAC1D,kEAAkE;QAClE,MAAM,IAAI,GAAG,MAAM,YAAE,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;YACzC,KAAK,EAAE,IAAA,gBAAE,EAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC;YACjC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,EAAE,8BAA8B;SACjF,CAAC,CAAA;QAEF,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,eAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,6CAA6C,CAAC,CAAA;YACvE,OAAM;QACR,CAAC;QAED,iEAAiE;QACjE,IAAI,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,gBAAgB,GAAG,YAAY,EAAE,CAAC;YAClE,eAAM,CAAC,IAAI,CACT,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,CAAC,gBAAgB,EAAE,EAC1D,uFAAuF,CACxF,CAAA;YACD,OAAM;QACR,CAAC;QAED,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAA;QAElC,4DAA4D;QAC5D,MAAM,cAAc,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,CAAA;QAC7C,cAAc,CAAC,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAA,CAAC,gBAAgB;QAEvE,gEAAgE;QAChE,yGAAyG;QACzG,MAAM,uBAAuB,GAAG,MAAM,YAAE;aACrC,MAAM,EAAE;aACR,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;aACzB,KAAK,CACJ,IAAA,iBAAG,EACD,IAAA,gBAAE,EAAC,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,EACvC,IAAA,iBAAG,EAAC,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,YAAY,CAAC,EAAE,yCAAyC;QAC5F,IAAA,gBAAE,EACA,IAAA,oBAAM,EAAC,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,gBAAgB;QACxD,IAAA,gBAAE,EAAC,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,4BAA4B;SAChF,CACF,CACF;YACD,uDAAuD;aACtD,OAAO,CACN,IAAA,iBAAG,EAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,EACjC,IAAA,iBAAG,EAAC,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,CACpC,CAAA;QAEH,gCAAgC;QAChC,IAAI,cAAc,GAAG,CAAC,CAAA;QAEtB,0DAA0D;QAC1D,IAAI,iBAAiB,GAAG,eAAe,CAAA;QAEvC,eAAM,CAAC,KAAK,CACV,EAAE,MAAM,EAAE,eAAe,EAAE,WAAW,EAAE,uBAAuB,CAAC,MAAM,EAAE,EACxE,wCAAwC,CACzC,CAAA;QAED,gCAAgC;QAChC,KAAK,MAAM,KAAK,IAAI,uBAAuB,EAAE,CAAC;YAC5C,MAAM,qBAAqB,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;YACvE,MAAM,oBAAoB,GAAG,KAAK,CAAC,MAAM,GAAG,qBAAqB,CAAA;YACjE,iBAAiB,IAAI,qBAAqB,CAAA;YAE1C,eAAM,CAAC,KAAK,CACV;gBACE,MAAM;gBACN,OAAO,EAAE,KAAK,CAAC,YAAY;gBAC3B,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,WAAW,EAAE,KAAK,CAAC,MAAM;gBACzB,QAAQ,EAAE,qBAAqB;gBAC/B,gBAAgB,EAAE,oBAAoB;gBACtC,kBAAkB,EAAE,iBAAiB;aACtC,EACD,6CAA6C,CAC9C,CAAA;YAED,qCAAqC;YACrC,IACE,oBAAoB,GAAG,CAAC;gBACxB,oBAAoB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EACzC,CAAC;gBACD,cAAc,IAAI,oBAAoB,CAAA;gBACtC,eAAM,CAAC,KAAK,CACV;oBACE,MAAM;oBACN,OAAO,EAAE,KAAK,CAAC,YAAY;oBAC3B,eAAe,EAAE,oBAAoB;oBACrC,gBAAgB,EAAE,cAAc;iBACjC,EACD,sCAAsC,CACvC,CAAA;YACH,CAAC;YAED,IAAI,iBAAiB,IAAI,CAAC,EAAE,CAAC;gBAC3B,yEAAyE;gBACzE,MAAM,eAAe,GAAG,uBAAuB,CAAC,KAAK,CACnD,uBAAuB,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAC3C,CAAA;gBACD,KAAK,MAAM,cAAc,IAAI,eAAe,EAAE,CAAC;oBAC7C,IAAI,oBAAoB,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;wBACvD,cAAc,IAAI,cAAc,CAAC,MAAM,CAAA;wBACvC,eAAM,CAAC,KAAK,CACV;4BACE,MAAM;4BACN,OAAO,EAAE,cAAc,CAAC,YAAY;4BACpC,eAAe,EAAE,cAAc,CAAC,MAAM;4BACtC,gBAAgB,EAAE,cAAc;yBACjC,EACD,gDAAgD,CACjD,CAAA;oBACH,CAAC;gBACH,CAAC;gBACD,MAAK,CAAC,0BAA0B;YAClC,CAAC;QACH,CAAC;QAED,eAAM,CAAC,IAAI,CACT,EAAE,MAAM,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,EAC/D,+BAA+B,CAChC,CAAA;QAED,iDAAiD;QACjD,MAAM,YAAE,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YAChC,4CAA4C;YAC5C,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;gBACvB,MAAM,eAAe,GAAG,YAAY,MAAM,IAAI,YAAY,CAAC,WAAW,EAAE,EAAE,CAAA;gBAC1E,MAAM,EAAE;qBACL,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;qBAC3B,MAAM,CAAC;oBACN,YAAY,EAAE,eAAe;oBAC7B,OAAO,EAAE,MAAM;oBACf,MAAM,EAAE,cAAc;oBACtB,gBAAgB,EAAE,cAAc,EAAE,iDAAiD;oBACnF,IAAI,EAAE,UAAU,EAAE,8BAA8B;oBAChD,QAAQ,EAAE,qCAAgB,CAAC,QAAQ,EAAE,uBAAuB;oBAC5D,UAAU,EAAE,IAAI,EAAE,gCAAgC;oBAClD,WAAW,EAAE,8BAA8B,YAAY,CAAC,kBAAkB,EAAE,EAAE;oBAC9E,2CAA2C;iBAC5C,CAAC;qBACD,mBAAmB,EAAE,CAAA,CAAC,gDAAgD;gBACzE,eAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE,yBAAyB,CAAC,CAAA;YACrE,CAAC;iBAAM,CAAC;gBACN,eAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,8BAA8B,CAAC,CAAA;YAC1D,CAAC;YAED,uDAAuD;YACvD,MAAM,aAAa,GAAG,IAAA,yBAAiB,EAAC,YAAY,CAAC,CAAA,CAAC,uDAAuD;YAC7G,MAAM,EAAE;iBACL,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;iBACnB,GAAG,CAAC;gBACH,KAAK,EAAE,CAAC;gBACR,gBAAgB,EAAE,aAAa;aAChC,CAAC;iBACD,KAAK,CAAC,IAAA,gBAAE,EAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAA;YAEpC,eAAM,CAAC,IAAI,CACT,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,CAAC,WAAW,EAAE,EAAE,EACtD,8CAA8C,CAC/C,CAAA;QACH,CAAC,CAAC,CAAA;QAEF,eAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,0CAA0C,CAAC,CAAA;IACrE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,eAAM,CAAC,KAAK,CACV,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,EAC/B,+BAA+B,CAChC,CAAA;QACD,6EAA6E;QAC7E,MAAM,KAAK,CAAA,CAAC,oDAAoD;IAClE,CAAC;AACH,CAAC"}

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"}