Credit System

Subscription Created
    |
    v
Credits Initialized (tier allocation)
    |--- Free: 500 credits
    |--- Basic: 1,500 credits
    |--- Pro: 5,000 credits
    |--- Enterprise: 15,000 credits
    |
    v
User Performs AI Operations
    |--- Each operation costs credits (5 - 80)
    |--- Atomic deduction with SELECT FOR UPDATE
    |--- Immutable CreditTransaction log entry
    |
    v
Monthly Reset (triggered by billing payment)
    |--- subscription_payment_success webhook
    |--- Credits restored to tier allocation
    |--- creditsResetAt updated to NOW
    |--- Auto-reset backup after 30 days
    |
    v
Cycle Repeats

export function getDefaultCreditsByTier(tier: SubscriptionTier): number {
  const tierCredits: CreditTierMap = {
    free: parseCreditsWithFallback(process.env.CREDIT_SYSTEM_FREE_CREDITS, 500),
    basic: parseCreditsWithFallback(
      process.env.CREDIT_SYSTEM_BASIC_CREDITS,
      1500
    ),
    pro: parseCreditsWithFallback(process.env.CREDIT_SYSTEM_PRO_CREDITS, 5000),
    enterprise: parseCreditsWithFallback(
      process.env.CREDIT_SYSTEM_ENTERPRISE_CREDITS,
      15000
    ),
  }

  return tierCredits[tier]
}

export function isCreditSystemEnabled(): boolean {
  // Return cached value if available
  if (creditSystemEnabledCache !== null) {
    return creditSystemEnabledCache
  }

  // Check pricing model (credit_based = credits enabled, classic_saas = unlimited)
  const pricingModel = process.env.NEXT_PUBLIC_PRICING_MODEL

  // CRITICAL: Distinguish between test types (unit vs E2E)
  // Unit tests (Vitest): ENABLE credit system to test credit logic
  //   - Set ENABLE_CREDIT_SYSTEM_IN_TESTS=true in vitest.config.ts
  //   - Mock Prisma directly for controlled testing
  // E2E tests (Playwright): DISABLE credit system (no database in CI)
  //   - Do NOT set ENABLE_CREDIT_SYSTEM_IN_TESTS flag
  //   - Tests run without database write operations
  const isUnitTest = process.env.ENABLE_CREDIT_SYSTEM_IN_TESTS === 'true'
  const isE2ETest = process.env.NODE_ENV === 'test' && !isUnitTest

  const enabled = pricingModel === 'credit_based' && !isE2ETest

  // Cache the result
  creditSystemEnabledCache = enabled

  // Log status once in development
  if (
    process.env.NODE_ENV === 'development' &&
    !globalThis.__creditSystemLoggedOnce
  ) {
    console.log(
      `[Credit System] ${enabled ? 'Enabled' : 'Disabled'} ` +
        `(MODEL=${pricingModel || 'undefined'}, isUnitTest=${isUnitTest}, isE2ETest=${isE2ETest})`
    )
    globalThis.__creditSystemLoggedOnce = true
  }

  return enabled
}

export async function deductCredits(params: {
  userId: string
  operation: CreditOperation
  quantity?: number
  metadata?: Prisma.InputJsonValue
}): Promise<CreditOperationResult> {
  const { userId, operation, quantity = 1, metadata } = params

  // Calculate cost based on operation type and quantity
  const cost = calculateBatchCost(operation, quantity)

  console.log(
    `[Credits] Deducting ${cost} credits for ${operation} (x${quantity})`
  )

  // Skip if credit system disabled
  if (!isCreditSystemEnabled()) {
    console.log('[Credits] System disabled - skipping deduction')
    return {
      success: true,
      balance: 999999, // Unlimited
      message: 'Credit system disabled',
    }
  }

  try {
    // Ensure credits initialized before deducting
    await ensureUserCreditsInitializedSafe(userId)

    // Use transaction to atomically check balance and deduct credits
    const result = await prisma.$transaction(
      async (tx) => {
        // CRITICAL: Lock user row with SELECT FOR UPDATE to prevent race conditions
        // This ensures only ONE transaction can read and modify the balance at a time
        const userRows = await tx.$queryRaw<
          Array<{ creditBalance: Decimal; creditsPerMonth: Decimal }>
        >`
        SELECT "creditBalance", "creditsPerMonth"
        FROM "User"
        WHERE "id" = ${userId}
        FOR UPDATE
      `

        if (!userRows || userRows.length === 0) {

import { deductCredits } from '@/lib/credits/credit-manager'

const result = await deductCredits({
  userId: 'user_database_id',
  operation: 'chat_message',  // Type-safe operation name
  quantity: 1,                 // Number of operations (default: 1)
  metadata: { model: 'gpt-4' } // Optional metadata for the ledger
})

if (result.success) {
  // Proceed with the AI operation
  console.log(`Remaining balance: ${result.balance}`)
} else {
  // Handle insufficient credits
  console.log(result.message) // "Insufficient credits. Required: 1, Available: 0"
}

const result = await deductCredits({ userId, operation: 'image_gen' })

if (!result.success) {
  return NextResponse.json(
    {
      error: 'Insufficient credits',
      required: getCreditCost('image_gen'),
      available: result.balance,
      upgradeUrl: '/dashboard/billing',
    },
    { status: 402 }
  )
}

# Basic tier packages
NEXT_PUBLIC_BONUS_BASIC_PACKAGE1_CREDITS="500"
NEXT_PUBLIC_BONUS_BASIC_PACKAGE1_PRICE="4.99"
NEXT_PUBLIC_BONUS_BASIC_PACKAGE1_VARIANT_ID="334455"

NEXT_PUBLIC_BONUS_BASIC_PACKAGE2_CREDITS="1200"
NEXT_PUBLIC_BONUS_BASIC_PACKAGE2_PRICE="9.99"
NEXT_PUBLIC_BONUS_BASIC_PACKAGE2_VARIANT_ID="334456"

/dashboard/credits
    |
    v
BonusPackages component (loads via GET /api/credits/bonus-packages)
    |--- Displays tier-specific packages with prices
    |--- Shows "Best Value" badge on cheapest per-credit package
    |--- Disables purchases when monthly limit reached
    |
    v
User clicks "Buy" → POST /api/credits/checkout
    |--- Validates variant ID against tier packages
    |--- Checks monthly purchase limit
    |--- Creates Lemon Squeezy checkout (one-time purchase)
    |
    v
Lemon Squeezy checkout page → User completes payment
    |
    v
order_created webhook → purchaseBonusCredits()
    |--- Idempotency check (lemonSqueezyId unique constraint)
    |--- Increments user.bonusCredits atomically
    |--- Records BonusCreditPurchase with expiration date
    |--- Logs "purchase" transaction in credit ledger
    |--- Sends confirmation email (non-blocking)
    |
    v
Redirect to /dashboard/credits?purchase=success
    |--- Success banner with auto-dismiss after 30 seconds
    |--- Polls credit balance for 30s to reflect new purchase

User has: 50 bonus credits + 100 subscription credits
Deduct 75 credits:

1. Bonus only (if bonus >= cost)
   → Use 75 bonus credits

2. Mixed (if bonus < cost but total >= cost)
   → Use 50 bonus + 25 subscription credits

3. Insufficient (if total < cost)
   → Deduction fails, no credits consumed

User has: 50 bonus credits + 100 subscription credits
Deduct 75 credits:

1. Subscription only (if subscription >= cost)
   → Use 75 subscription credits

2. Bonus fallback (if subscription < cost but total >= cost)
   → Use 100 subscription + draw remaining from bonus

3. Insufficient (if total < cost)
   → Deduction fails, no credits consumed

// Get all transactions for a user
const transactions = await prisma.creditTransaction.findMany({
  where: { userId },
  orderBy: { createdAt: 'desc' },
  take: 50,
})

// Get usage summary by operation type
const usageSummary = await prisma.creditTransaction.groupBy({
  by: ['operation'],
  where: { userId, type: 'usage' },
  _sum: { amount: true },
  _count: true,
})