Function grantCreditOperation

packages/billing/src/grant-credits.ts:258–286

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

 * When called without a transaction, acquires the advisory lock automatically.
 */
export async function grantCreditOperation(params: {
  userId: string
  amount: number
  type: GrantType
  description: string
  expiresAt: Date | null
  operationId: string
  tx?: DbTransaction
  logger: Logger
}) {
  const { userId, tx, logger } = params

  // If a transaction is provided, the caller is responsible for locking
  // (e.g., triggerMonthlyResetAndGrant which does multiple grants in one tx)
  if (tx) {
    await executeGrantCreditOperation({ ...params, tx })
    return
  }

  // Otherwise, wrap in advisory lock to serialize with other credit operations for this user
  await withAdvisoryLockTransaction({
    callback: async (tx) => {
      await executeGrantCreditOperation({ ...params, tx })
    },
    lockKey: `user:${userId}`,
    context: { userId, operationId: params.operationId, type: params.type },
    logger,
  }).then(({ result }) => result)
}

/**
 * Processes a credit grant request with retries and failure logging.