SudoSOS Back-end API / balance

Balance

A user's balance is the net of every transaction and Transfer on their account. Positive means SudoSOS owes them; negative means they owe SudoSOS and need to top up.

Computed, not authoritative

The source of truth is Transaction and Transfer history. The Balance table is a cache, so reading one user's balance does not have to re-sum every SubTransactionRow since their first deposit.

Cache structure

Each row stores the cached amount plus a lastTransactionId / lastTransferId cursor. getBalances returns cachedAmount + delta, where the delta sums every sub-transaction row and transfer that happened after the cursor. If the cache is out of date the read still returns the correct value; it just costs more SQL.

updateBalances writes a fresh total back to the cache. clearBalanceCache drops cache rows -- useful after bulk-rewriting history.

What moves a balance

Sub-transaction rows debit the SubTransaction buyer (fromId) and credit the seller (toId, the container owner). Prices are pinned by the ProductRevision in effect at the time, so editing a product later does not retroactively shift balances.

Transfers are the explicit movements outside a transaction: Stripe deposits, fine handouts, fine waivers, payout requests, seller payouts, write-offs, invoices.

Undoing either of those writes a compensating row; the original stays in the audit trail.

Fines on the response

BalanceResponse carries the user's outstanding fine amount, the timestamp of the first fine, the number of fines, and any waived amount. These are "now" values, not historical -- ignore them when date is in the past.

Total balances

GET /balances/summary adds up positive and negative balances across the database, broken down by UserType. Treasurers use it to reconcile SudoSOS against the bank account.

POS users

POS users do not hold balances of their own. Their sub-transactions credit the container owner, and balance queries filter POS users out at the SQL level, so they never show up in PaginatedBalanceResponse or TotalBalanceResponse.

Enumerations

Enumeration	Description
BalanceOrderColumn	-

Classes

Class	Description
Balance	TypeORM entity for the balance table. This is a cache row -- the authoritative balance is recomputed from Transaction and Transfer history. lastTransaction and lastTransfer mark the cursor up to which amount is accurate; anything newer is summed on read by BalanceService.
BalanceController	Controller for the balance module. All endpoints are reads -- you cannot mutate a balance directly; record a transaction or a transfer and the next read picks it up. See the module page for how balances are computed.
BalanceService	-

Interfaces

Interface	Description
BalanceResponse	-
GetBalanceParameters	-
PaginatedBalanceResponse	-
TotalBalanceResponse	-
UpdateBalanceParameters	-
UserTypeTotalBalanceResponse	-

Functions

Function	Description
asBalanceOrderColumn	Converts the input to an VatDeclarationPeriod