finance

type Client ¶

type Client = types.FinanceClient

Client is the in-process inter-subsystem seam cloud's money paths call. It IS cloud's types.FinanceClient — one narrow interface (BalanceCents + Deposit + RecordUsage), kept as an alias so a value satisfies both names with no adapter (mirrors commerce.Client).

func Current() Client

type Kind ¶ added in v1.801.350

type Kind string

Kind classifies a wallet entry's economic meaning — money IN or money OUT — and is also the first half of the entry's idempotency key. Kept small and closed: two directions, two names.

IT IS THE ONE VOCABULARY, and it is a TYPE rather than a pair of strings because both halves of the money surface read it. The ledger WRITES these kinds and the customer's finance pages CLASSIFY on them, and while the reader held its own string literals the two silently disagreed: the reader matched commerce's `deposit` / `withdraw` against entries this file has always written as `finance.deposit` / `finance.usage`, so over the peer path a customer's credits rendered empty, their usage totalled zero, and their own top-up signed NEGATIVE. Nothing failed — the strings just never met. Named constants of a named type make that disagreement a compile error instead of a wrong number on a customer's balance page.

const (
	KindDeposit Kind = "finance.deposit" // funding:platform → wallet (a prepaid grant/settlement)
	KindUsage   Kind = "finance.usage"   // wallet → revenue:platform (a metered debit)
	// KindUnknown is what a kind the ledger never wrote parses to. A reader treats it
	// as neither direction rather than guessing one — an entry nobody can classify
	// must not be silently counted as spend.
	KindUnknown Kind = ""
)

func ParseKind(s string) Kind

type TxnRow ¶ added in v1.801.350

type TxnRow struct {
	ID        string
	Kind      Kind
	Ref       string
	Memo      string
	Amount    money.Amount
	CreatedAt int64
}

TxnRow is one ledger entry as the billing surface reads it: every kind, not only the usage debits ListUsage keeps. Credits, grants and debits are all transactions to a customer looking at their account, and the three finance pages (credits/usage/ledger) are three projections of THIS one list.

Amount stays the ledger's own money.Amount — 18-decimal exact, the same integer an on-chain balance holds — because this is where that value lives. Flattening to cents here would round away everything below a cent, which is most of what a per-token AI price IS.

Kind is the ledger's OWN Kind, not a string: a customer-facing page decides whether a row is money in or money out by comparing it, and a reader holding its own string literals is how the credits page came to render empty against a ledger full of grants.

type UsageRow ¶

type UsageRow struct {
	ID    string `json:"id"`
	Cents int64  `json:"cents"`
	// Amount is the debit exactly as the ledger holds it — the same 18-decimal
	// value the wallet→revenue posting moved. Cents beside it is the ROUNDING of
	// this value, kept for the wires that already carry cents; it is never the
	// source. TxnRow below has said why since it was written: "Flattening to
	// cents here would round away everything below a cent, which is most of what
	// a per-token AI price IS" — and this row, read from the SAME ledger, was
	// flattening. A customer whose usage was a thousand sub-cent calls read back
	// a page of zeros that summed to zero.
	Amount    money.Amount `json:"amount"`
	Model     string       `json:"model"`
	CreatedAt int64        `json:"createdAt"`
}

UsageRow is one recorded usage debit — the READ twin of RecordUsage. The SAME wallet→revenue posting a metered call wrote is read back here, so the usage a customer SEES is exactly what drained their wallet. Cents is the debit magnitude (USD minor units); Model is the metered-unit label the debit carried (Entry.Memo); CreatedAt is unix seconds.