Function executeGrantCreditOperation

packages/billing/src/grant-credits.ts:117–251

* Core grant operation that performs the actual credit grant logic. * This should be called within a transaction that holds the appropriate advisory lock. * Uses ON CONFLICT DO NOTHING for idempotency - duplicate grants are silently ignored.

(params: {
  userId: string
  amount: number
  type: GrantType
  description: string
  expiresAt: Date | null
  operationId: string
  tx: DbTransaction
  logger: Logger
})

 * Uses ON CONFLICT DO NOTHING for idempotency - duplicate grants are silently ignored.
 */
async function executeGrantCreditOperation(params: {
  userId: string
  amount: number
  type: GrantType
  description: string
  expiresAt: Date | null
  operationId: string
  tx: DbTransaction
  logger: Logger
}) {
  const {
    userId,
    amount,
    type,
    description,
    expiresAt,
    operationId,
    tx,
    logger,
  } = params

  const now = new Date()

  // First check for any negative balances.
  // This is the ONLY place debt is cleared. The consume path
  // (consumeFromOrderedGrants in balance-calculator.ts) only deepens
  // debt on overflow; it never repays it. New credit grants zero out
  // existing debt rows here and subtract the total debt from the
  // granted amount.
  const negativeGrants = await tx
    .select()
    .from(schema.creditLedger)
    .where(
      and(
        eq(schema.creditLedger.user_id, userId),
        or(
          isNull(schema.creditLedger.expires_at),
          gt(schema.creditLedger.expires_at, now),
        ),
      ),
    )
    .then((grants) => grants.filter((g) => g.balance < 0))

  let inserted = false
  let fullyConsumedByDebt = false

  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(eq(schema.creditLedger.operation_id, grant.operation_id))
    }
    const remainingAmount = Math.max(0, amount - totalDebt)