Function consumeFromOrderedGrants

packages/billing/src/balance-calculator.ts:213–289

(
  params: {
    userId: string
    creditsToConsume: number
    grants: (typeof schema.creditLedger.$inferSelect)[]
    logger: Logger
  } & ParamsExcluding<
    typeof updateGrantBalance,
    'grant' | 'consumed' | 'newBalance'
  >,
)

 * new credits are added. This function only deepens debt on overflow.
 */
export async function consumeFromOrderedGrants(
  params: {
    userId: string
    creditsToConsume: number
    grants: (typeof schema.creditLedger.$inferSelect)[]
    logger: Logger
  } & ParamsExcluding<
    typeof updateGrantBalance,
    'grant' | 'consumed' | 'newBalance'
  >,
): Promise<CreditConsumptionResult> {
  const { userId, creditsToConsume, grants, logger } = params

  let remainingToConsume = creditsToConsume
  let consumed = 0
  let fromPurchased = 0

  // Consume from positive balances in priority order.
  // NOTE: debt grants (balance < 0) are skipped. Consumption never repays
  // debt; that only happens via grant-credits.ts when new credits arrive.
  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({
      ...params,
      grant,
      consumed: consumeFromThisGrant,
      newBalance,
    })

    // Mutate in-memory balance so the overflow check below sees
    // post-consumption state (not the stale original value).
    grant.balance = newBalance
  }

  // If we still have remaining to consume, create or extend debt on the
  // last grant. After the loop above all positive-balance grants are drained.
  // The "last grant" (lowest consumption priority, typically a subscription
  // grant that renews monthly) absorbs the overflow as debt.
  if (remainingToConsume > 0 && grants.length > 0) {
    const lastGrant = grants[grants.length - 1]
    const newBalance = lastGrant.balance - remainingToConsume

    await updateGrantBalance({
      ...params,
      grant: lastGrant,
      consumed: remainingToConsume,