urpx.price — energy.grid-coordination/clj-urpx 0.1.0

Resolve applicable per-energy prices for a URPX rate plan at a given instant.

Given a coerced rate plan (urpx.coerce/coerce-rate-plan) and a ZonedDateTime, resolve-prices returns the season, the matched TOU period (if any), and one entry per active per-energy ledger (commodity, distribution, public benefits, etc.). Each ledger entry carries a :tiers vector — for block-tiered ledgers (CPAU E-1) every tier's bound and unit-price is surfaced so the caller can pick the active one based on cumulative usage; for non-tiered ledgers the vector has a single entry.

Skipped:

• PriceDefinitions whose own :urpx/hasCalculationMethod is set (recurring fixed charges like a monthly customer charge — these are subscription-style and don't apply to instantaneous lookup).

Day types honored: urpx:allDays, urpx:weekday, urpx:weekend, urpx:holiday. Holiday matching requires the caller to pass a :holiday? predicate (LocalDate -> bool); without it, urpx:holiday brackets never match.

marginal-unit-rate clj

(marginal-unit-rate resolved)

Sum the unit prices across all ledgers, picking the LOWEST tier in each block-tiered ledger as the marginal rate at the start of a billing period.

Useful for price signaling: when you don't know a customer's usage but want a single $/kWh number, this is the marginal rate at zero baseline usage.

resolve-prices clj

(resolve-prices rate-plan zdt)

(resolve-prices rate-plan zdt opts)

Resolve all per-energy unit prices that apply to rate-plan at zdt (a java.time.ZonedDateTime in the rate plan's local timezone).

Optional opts map: :holiday? predicate (LocalDate -> bool) used to decide whether the query date hits a urpx:holiday day-type bracket. A plain set of LocalDates works (sets are functions). When omitted, urpx:holiday brackets never match.

Examples of :holiday?:

;; Static set — quickest to set up: (def us-federal-2026 #{(LocalDate/of 2026 1 1) ; New Year's Day (LocalDate/of 2026 1 19) ; Martin Luther King Jr. Day (LocalDate/of 2026 2 16) ; Presidents Day (LocalDate/of 2026 5 25) ; Memorial Day (LocalDate/of 2026 6 19) ; Juneteenth (LocalDate/of 2026 7 3) ; Independence Day (observed) (LocalDate/of 2026 9 7) ; Labor Day (LocalDate/of 2026 11 11) ; Veterans Day (LocalDate/of 2026 11 26) ; Thanksgiving (LocalDate/of 2026 12 25)}) ; Christmas (resolve-prices plan zdt {:holiday? us-federal-2026})

;; Composed predicate — if you maintain a calendar elsewhere: (resolve-prices plan zdt {:holiday? (fn [d] (calendar/observed? :us-federal d))})

Returns: {:urpx.resolved/season-name String or nil :urpx.resolved/tou-period-name String or nil :urpx.resolved/tou-period-number int or nil :urpx.resolved/ledgers [LedgerResult]}

where each LedgerResult is: {:urpx.resolved/ledger-id String :urpx.resolved/ledger-name String :urpx.resolved/ledger-type Ref :urpx.resolved/tiers [TierResult]}

and each TierResult is: {:urpx.resolved/price-definition-id String :urpx.resolved/price-id String :urpx.resolved/price-name String :urpx.resolved/unit-price BigDecimal :urpx.resolved/tier-number int (only on block-tiered ledgers) :urpx.resolved/tier-name String :urpx.resolved/tier-lower-bound BigDecimal :urpx.resolved/tier-upper-bound BigDecimal :urpx.resolved/tier-lower-bound-operator Ref :urpx.resolved/tier-upper-bound-operator Ref}

For non-tiered ledgers, :tiers has a single entry with no tier-* keys. For block-tiered ledgers (e.g. CPAU E-1), :tiers carries every tier sorted by tier-number — the caller chooses based on cumulative billing-period usage.