Function consumeCredits

packages/billing/src/balance-calculator.ts:443–519

(params: {
  userId: string
  stripeCustomerId?: string | null
  creditsToConsume: number
  logger: Logger
})

 * @returns Promise resolving to number of credits consumed
 */
export async function consumeCredits(params: {
  userId: string
  stripeCustomerId?: string | null
  creditsToConsume: number
  logger: Logger
}): Promise<CreditConsumptionResult> {
  const { userId, creditsToConsume, logger } = params

  const { result, lockWaitMs } = await withAdvisoryLockTransaction({
    callback: async (tx) => {
      const now = new Date()
      const activeGrants = await getOrderedActiveGrantsForConsumption({
        ...params,
        now,
        conn: tx,
      })

      if (activeGrants.length === 0) {
        logger.error(
          { userId, creditsToConsume },
          'No active grants found to consume credits from',
        )
        throw new Error('No active grants found')
      }

      const consumeResult = await consumeFromOrderedGrants({
        ...params,
        creditsToConsume,
        grants: activeGrants,
        tx,
      })

      return consumeResult
    },
    lockKey: `user:${userId}`,
    context: { userId, creditsToConsume },
    logger,
  })

  // Log successful credit consumption with lock timing
  logger.info(
    {
      userId,
      creditsConsumed: result.consumed,
      creditsRequested: creditsToConsume,
      fromPurchased: result.fromPurchased,
      lockWaitMs,
    },
    'Credits consumed',
  )

  // Track credit consumption analytics
  trackEvent({
    event: AnalyticsEvent.CREDIT_CONSUMED,
    userId,
    properties: {
      creditsConsumed: result.consumed,
      creditsRequested: creditsToConsume,