feat(currencies): refactor currencies package

Author: mark-vass-konghq

.agents/skills/currencyx/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: currencyx
+description: Work on OpenMeter currency primitives in pkg/currencyx for fiat and custom currency codes, shared currency interfaces, rounding modes, calculators, allocation precision, fiat/custom boundaries, and callers in billing, charges, ledger, product catalog, subscriptions, API, or currency registry code.
+---
+
+# Currencyx
+
+Use this skill when changes touch `pkg/currencyx` or any caller that depends on currency code shape, fiat/custom classification, calculator behavior, rounding, allocation, or invoice/ledger currency boundaries.
+
+Also load the domain skill for each touched caller area: `billing`, `charges`, `ledger`, `subscription`, `api`, `ent`, `db-migration`, and `test`.
+
+## Source Of Truth
+
+- Source code: `pkg/currencyx/*.go`.
+- Primary tests: `pkg/currencyx/*_test.go`.
+- Package usage examples: `pkg/currencyx/README.md`.
+- This skill is a how-to/reference for agents. Update it whenever `Currency`, `Code`, `CustomCurrency`, `Calculator`, rounding, allocation, or validation behavior changes.
+- One canonical repo skill lives at `.agents/skills/currencyx`; do not create duplicate currencyx guidance elsewhere.
+
+## Package Layout
+
+- `currency.go`: currency type constants, the shared `Currency` interface, `Code`, `CustomCurrency`, and fiat/custom constructors.
+- `validation.go`: code format validation, fiat collision checks, precision validation, `PostgresCodeSchemaType`, and `CustomCurrency.Validate`.
+- `fiat.go`: rounding modes, `Calculator`, and precision helpers.
+- `allocation.go`: deterministic largest-remainder allocation using calculator precision.
+- `README.md`: short examples for fiat, custom, and allocation usage.
+
+## Boundary Model
+
+- **Currency code**: durable identifier. Fiat and custom codes use `currencyx.Code`, but validation differs by boundary.
+- **Currency interface**: shared behavior contract. Callers that know a configured currency should expose `CurrencyCode()`, `CurrencyType()`, `CurrencyPrecision()`, and `CurrencyRoundingMode()`.
+- **Fiat currency**: `currencyx.Code` implements `currencyx.Currency` as fiat. `Code.Calculator()` preserves existing fiat behavior and derives precision from GOBL/ISO definitions.
+- **Custom currency**: `currencyx.CustomCurrency` implements `currencyx.Currency`. Custom currencies carry configured precision and rounding mode; missing rounding mode defaults to bankers rounding.
+- **Calculator**: construct with `currencyx.NewCalculator(currencyx.Currency)`. The calculator must branch from `CurrencyType()` and use `CurrencyPrecision()` / `CurrencyRoundingMode()` from the interface for custom currencies.
+- **Allocation**: use calculator precision for units and largest-remainder distribution. Do not reach into fiat-only `Def.Subunits` for allocation logic.
+- **Validation**: `Code.Validate()` remains fiat semantic for existing callers. Use `ValidateFormat()` for structural code checks and `ValidateCustom()` for custom currency codes. Custom codes must not contain the `|` route delimiter.
+- **Registry boundary**: owns custom currency definition, fiat-code collision checks, archive/activation rules, and future persisted rounding configuration.
+- **Finance boundary**: snapshots fiat basis and applies fiat rounding when custom units become fiat amounts.
+- **Ledger boundary**: records durable currency codes and balanced single-currency legs. Round before posting only when the upstream domain owns normalization.
+- **Invoice boundary**: invoice currency stays fiat. Custom units must be materialized to fiat before invoice artifacts.
+
+## Rounding Rules
+
+- Preserve fiat rounding unless the task explicitly changes fiat money behavior.
+- Custom currency default rounding is `RoundingModeBankers` (`RoundBank`, half-even).
+- Custom currencies can opt into `RoundingModeHalfAwayFromZero` through `NewCustomCurrencyWithRounding`.
+- `Calculator.RoundToPrecision` is the single place that applies the effective rounding mode.
+- `Calculator.RoundDown` and `Calculator.Unit` are precision helpers; they should not apply banker/half-away rounding.
+- `Calculator.IsRoundedToPrecision` must use `RoundToPrecision`, so it follows the configured rounding mode.
+
+## Process
+
+1. Name the surface before editing: code validation, type/interface, rounding, calculator, allocation, registry, ledger fact, fiat materialization, or invoice boundary.
+2. Keep `pkg/currencyx` free of imports from `openmeter/...`; callers can implement `currencyx.Currency` to supply registry-backed custom settings.
+3. Prefer `CurrencyType()` at the boundary that truly requires fiat or custom. Do not add broad split helpers unless the caller boundary needs a named domain rule.
+4. Preserve `currencyx.Code(...).Calculator()` for existing fiat callers.
+5. For custom currencies, validate structural code, route delimiter exclusion, fiat-code collisions, precision, and rounding mode.
+6. Keep allocation deterministic: precision defines units, largest remainder distributes residual units, and tie-breakers remain stable.
+7. After editing, run focused `pkg/currencyx` tests, `go vet`, and caller tests or compile checks for every touched boundary.
+
+## Test Checklist
+
+Cover the named risk introduced by the change:
+
+- Fiat regression behavior: code validation, precision from ISO definition, and existing rounding.
+- Validation boundaries: `Code.Validate()` stays fiat-only while `ValidateFormat()` accepts structurally valid custom codes.
+- Custom interface behavior: code, type, precision, and rounding mode all flow through `currencyx.Currency`.
+- Banker ties: positive, negative, and zero-precision custom rounding tie to even.
+- Alternate custom rounding: half-away-from-zero remains selectable and tested.
+- Invalid config: bad precision or rounding mode fails validation.
+- Allocation precision: custom precision affects units and largest-remainder allocation.
+- Boundary tests: billing/invoice rejects custom invoice currency explicitly; ledger accepts structurally valid custom codes only when that domain supports them.
+
+Focused commands:
+
+```bash
+env GOCACHE=/private/tmp/openmeter-go-build go test ./pkg/currencyx
+env GOCACHE=/private/tmp/openmeter-go-build go vet ./pkg/currencyx
+```
+
+For caller compile checks, keep the package list scoped to touched boundaries and include `-tags=dynamic` when billing/ledger paths require it.
+
+## Review Checks
+
+- Fiat and custom currencies share the `currencyx.Currency` interface.
+- `Calculator.RoundToPrecision` applies the effective rounding rule.
+- `Calculator` does not require fiat definitions for custom currencies.
+- Allocation code uses calculator methods, not fiat-only definition fields.
+- Invalid rounding precision or mode fails validation.
+- Tests cover banker ties, configured custom precision, fiat regression behavior, invalid rounding config, and allocation precision.

.agents/skills/currencyx/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Currencyx"
+  short_description: "Work on fiat and custom currency primitives"
+  default_prompt: "Use $currencyx to update OpenMeter currency code, rounding, calculator, allocation, or fiat/custom boundary behavior."

pkg/currencyx/README.md

@@ -0,0 +1,48 @@
+# currencyx
+
+`currencyx` contains OpenMeter's shared currency primitives. It keeps fiat
+behavior compatible with GOBL/ISO currency definitions while allowing product
+and ledger code to pass configured custom currencies through the same
+`Currency` interface.
+
+## Fiat Currency
+
+Use `Code` directly for fiat currencies. Fiat precision comes from the GOBL
+currency definition and fiat rounding remains half-away-from-zero.
+
+```go
+calculator, err := currencyx.Code("USD").Calculator()
+if err != nil {
+    return err
+}
+
+amount := calculator.RoundToPrecision(alpacadecimal.RequireFromString("1.235"))
+// amount == 1.24
+```
+
+## Custom Currency
+
+Use `NewCustomCurrency` when the currency is not a known fiat code. Custom
+currencies carry explicit precision and default to bankers rounding
+(half-even). Use `NewCustomCurrencyWithRounding` to opt into half-away-from-zero.
+
+```go
+credits, err := currencyx.NewCustomCurrency(currencyx.Code("CREDITS"), 6)
+if err != nil {
+    return err
+}
+
+calculator, err := currencyx.NewCalculator(credits)
+if err != nil {
+    return err
+}
+
+amount := calculator.RoundToPrecision(alpacadecimal.RequireFromString("1.2345678"))
+// amount == 1.234568
+```
+
+## Allocation
+
+Allocation helpers use the calculator's precision and distribute residual units
+with a deterministic largest-remainder method. Provide a `CompareKey` function
+when equal remainders need a stable domain-specific tie-breaker.

pkg/currencyx/allocation.go

@@ -85,7 +85,7 @@ func AllocateByWeight[T any](calculator Calculator, input WeightedAllocationInpu
 	allocated := alpacadecimal.Zero
 	for i, item := range input.Items {
 		share := input.Amount.Mul(item.Weight).Div(totalWeight)
-		amount := share.RoundDown(int32(calculator.Def.Subunits))
+		amount := calculator.RoundDown(share)
 
 		candidates = append(candidates, allocationCandidate{
 			index:     i,
@@ -169,7 +169,7 @@ func AllocateByAmount[T any](calculator Calculator, input AmountAllocationInput[
 	allocated := alpacadecimal.Zero
 	for i, item := range input.Items {
 		share := input.Amount.Mul(item.Amount).Div(totalAmount)
-		floor := share.RoundDown(int32(calculator.Def.Subunits))
+		floor := calculator.RoundDown(share)
 
 		candidates = append(candidates, allocationCandidate{
 			index:     i,
@@ -312,5 +312,5 @@ func validateAmountAllocationInput[T any](calculator Calculator, input AmountAll
 }
 
 func currencyUnit(calculator Calculator) alpacadecimal.Decimal {
-	return alpacadecimal.NewFromInt(1).Shift(-int32(calculator.Def.Subunits))
+	return calculator.Unit()
 }

pkg/currencyx/allocation_test.go

@@ -87,6 +87,24 @@ func TestAllocateByWeight(t *testing.T) {
 		}, allocations)
 	})
 
+	t.Run("uses custom currency precision", func(t *testing.T) {
+		custom := testCustomCalculator(t, "CREDITS", 4)
+
+		allocations, err := currencyx.AllocateByWeight(custom, currencyx.WeightedAllocationInput[string]{
+			Amount: dec("0.0005"),
+			Items: []currencyx.WeightedAllocationItem[string]{
+				{Key: "A", Weight: dec("1")},
+				{Key: "B", Weight: dec("1")},
+			},
+		})
+		require.NoError(t, err)
+
+		requireAllocationsEqual(t, []currencyx.WeightedAllocation[string]{
+			{Key: "A", Amount: dec("0.0003")},
+			{Key: "B", Amount: dec("0.0002")},
+		}, allocations)
+	})
+
 	t.Run("omits zero allocations", func(t *testing.T) {
 		allocations, err := currencyx.AllocateByWeight(usd, currencyx.WeightedAllocationInput[string]{
 			Amount: dec("0.01"),
@@ -361,6 +379,18 @@ func testCalculator(t *testing.T, code string) currencyx.Calculator {
 	return calculator
 }
 
+func testCustomCalculator(t *testing.T, code string, precision int32) currencyx.Calculator {
+	t.Helper()
+
+	currency, err := currencyx.NewCustomCurrency(currencyx.Code(code), precision)
+	require.NoError(t, err)
+
+	calculator, err := currencyx.NewCalculator(currency)
+	require.NoError(t, err)
+
+	return calculator
+}
+
 func requireAllocationsEqual[T comparable](t *testing.T, expected, actual []currencyx.WeightedAllocation[T]) {
 	t.Helper()
 

pkg/currencyx/currency.go

@@ -1,60 +1,122 @@
 package currencyx
 
 import (
-	"errors"
+	"fmt"
 
-	"github.com/alpacahq/alpacadecimal"
 	"github.com/invopop/gobl/currency"
 )
 
-// Currency represents a currency code.
-// Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
-type Code currency.Code
+type CurrencyType string
+
+const (
+	CurrencyTypeFiat   CurrencyType = "fiat"
+	CurrencyTypeCustom CurrencyType = "custom"
+)
 
-func (c Code) Validate() error {
-	if c == "" {
-		return errors.New("currency code is required")
+func (t CurrencyType) Validate() error {
+	switch t {
+	case CurrencyTypeFiat, CurrencyTypeCustom:
+		return nil
+	default:
+		return fmt.Errorf("invalid currency type: %s", t)
 	}
+}
+
+type Currency interface {
+	CurrencyCode() Code
+	CurrencyType() CurrencyType
+	CurrencyPrecision() int32
+	CurrencyRoundingMode() RoundingMode
+}
+
+// Code represents a fiat or custom currency code. Code values used directly as
+// Currency values are treated as fiat currencies for backwards compatibility.
+type Code currency.Code
 
-	return currency.Code(c).Validate()
+func (c Code) String() string {
+	return string(c)
 }
 
-// Calculator provides a currency calculator object. This allows us to not to resolve def a lot of times, plus
-// we can assume that def is always valid, thus we can avoid a lot of error handling.
-func (c Code) Calculator() (Calculator, error) {
-	if err := c.Validate(); err != nil {
-		return Calculator{}, err
+func (c Code) CurrencyCode() Code {
+	return c
+}
+
+func (c Code) CurrencyType() CurrencyType {
+	return CurrencyTypeFiat
+}
+
+func (c Code) CurrencyPrecision() int32 {
+	def := currency.Get(currency.Code(c))
+	if def == nil {
+		return 0
 	}
 
-	return Calculator{
-		Currency: c,
-		Def:      currency.Get(currency.Code(c)),
-	}, nil
+	return int32(def.Subunits)
 }
 
-// TODO: Better name?!
-type Calculator struct {
-	Currency Code
-	Def      *currency.Def
+func (c Code) CurrencyRoundingMode() RoundingMode {
+	return RoundingModeHalfAwayFromZero
 }
 
-func (c Calculator) RoundToPrecision(amount alpacadecimal.Decimal) alpacadecimal.Decimal {
-	// TODO: For now we are skipping the smallestDenomination, as that is a reference to the coins
-	// in circulation, but should not be an issue for online payments.
-	return amount.Round(int32(c.Def.Subunits))
+type CustomCurrency struct {
+	Code         Code
+	Precision    int32
+	RoundingMode RoundingMode
 }
 
-func (c Calculator) Validate() error {
-	var errs []error
-	if err := c.Currency.Validate(); err != nil {
-		errs = append(errs, err)
+func NewCurrency(code Code, currencyType CurrencyType, precision int32) (Currency, error) {
+	switch currencyType {
+	case CurrencyTypeFiat:
+		return NewFiatCurrency(code)
+	case CurrencyTypeCustom:
+		return NewCustomCurrency(code, precision)
+	default:
+		return nil, currencyType.Validate()
 	}
-	if c.Def == nil {
-		errs = append(errs, errors.New("currency definition is required"))
+}
+
+func NewFiatCurrency(code Code) (Code, error) {
+	if err := code.Validate(); err != nil {
+		return "", err
+	}
+
+	if currency.Get(currency.Code(code)) == nil {
+		return "", fmt.Errorf("fiat currency definition is required for %s", code)
 	}
-	return errors.Join(errs...)
+
+	return code, nil
+}
+
+func NewCustomCurrency(code Code, precision int32) (CustomCurrency, error) {
+	return NewCustomCurrencyWithRounding(code, precision, RoundingModeBankers)
+}
+
+func NewCustomCurrencyWithRounding(code Code, precision int32, roundingMode RoundingMode) (CustomCurrency, error) {
+	out := CustomCurrency{
+		Code:         code,
+		Precision:    precision,
+		RoundingMode: roundingMode,
+	}
+
+	return out, out.Validate()
 }
 
-func (c Calculator) IsRoundedToPrecision(amount alpacadecimal.Decimal) bool {
-	return amount.Equal(c.RoundToPrecision(amount))
+func (c CustomCurrency) CurrencyCode() Code {
+	return c.Code
+}
+
+func (c CustomCurrency) CurrencyType() CurrencyType {
+	return CurrencyTypeCustom
+}
+
+func (c CustomCurrency) CurrencyPrecision() int32 {
+	return c.Precision
+}
+
+func (c CustomCurrency) CurrencyRoundingMode() RoundingMode {
+	if c.RoundingMode == "" {
+		return RoundingModeBankers
+	}
+
+	return c.RoundingMode
 }