feat: add balance API endpoint

apps/billing/services.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 
 from django.db import transaction
+from django.db.models import Sum
 
 from apps.users.models import UserWallet
 
@@ -46,6 +47,12 @@ class RefundResult:
     refunded: bool
 
 
+@dataclass(frozen=True)
+class BalanceSnapshot:
+    points_balance: int
+    ledger_balance: int
+
+
 def _validate_positive_points(points: int) -> int:
     if isinstance(points, bool) or not isinstance(points, int) or points <= 0:
         raise ValueError("points must be a positive integer")
@@ -57,6 +64,21 @@ def _locked_wallet_for_user(user) -> UserWallet:
     return wallet
 
 
+def get_balance_snapshot(user) -> BalanceSnapshot:
+    points_balance = (
+        UserWallet.objects.filter(user=user)
+        .values_list("points_balance", flat=True)
+        .first()
+    )
+    ledger_balance = PointsLedger.objects.filter(user=user).aggregate(
+        total=Sum("points_delta")
+    )["total"] or 0
+    return BalanceSnapshot(
+        points_balance=int(points_balance or 0),
+        ledger_balance=int(ledger_balance),
+    )
+
+
 def precharge_call(
     *,
     user,