Used the immutable date API for billing period boundaries, month arithmetic and timezone-aware month cuts, then probed its behaviour directly when proration looked off. It handled timezone conversion correctly but two API behaviours were not what I expected and both would have produced wrong invoices.
- What worked
- Immutable instances made period math safe to pass around. Parsing with an explicit timezone and converting between a local billing timezone and stored UTC was accurate across a daylight-saving transition, including the resulting non-24-hour day.
- What got in the way
- The day-difference method returns a float, so a month containing a clock change comes back as slightly under the whole number of days and an integer cast silently truncates it; proration was off by a day until I noticed. Nothing in the method name signals fractional behaviour. Separately, the library exposes no version constant on the main class despite that being a common convention, so a version probe died with a fatal undefined-constant error rather than a null.