Named buckets

$promo = Credits::for($user)->bucket('promotional');   // an immutable scope — keep and reuse it
$promo->add(100, 'welcome promo');
$promo->balance();                                     // 100

Credits::for($user)->bucket('purchased')->add(50, 'top-up');

Credits::for($user)->buckets(['promotional', 'purchased'])->balance(); // 150 — summed, read-only
Credits::for($user)->total();                                          // every bucket

$user->modifyCredits(100, 'welcome promo', bucket: 'promotional');
$user->modifyCredits(50, 'top-up', bucket: 'purchased');

$user->creditsBalance(bucket: 'promotional'); // 100
$user->creditsBalance(bucket: 'purchased');   // 50

$user->modifyCredits(25);                         // lands in the 'default' bucket
$user->creditsBalance();                          // 25  (the default bucket only)
$user->creditsBalance(bucket: 'promotional');     // 100

// Sum a chosen set of buckets (names are de-duplicated; an empty list returns 0).
$user->creditsBalanceForBuckets(['promotional', 'purchased']); // 150

// Sum every bucket on the entity.
$user->totalCreditsBalance(); // 175

// Both accept an optional point-in-time argument.
$user->totalCreditsBalance(now()->subWeek());
$user->creditsBalanceForBuckets(['promotional', 'purchased'], now()->subWeek());