feat(tariff): add Tariff V2 rate resolver

docs/fleet_api_energy_sites.md

@@ -345,14 +345,45 @@ async def main():
 
         try:
             energy_site = api.energySites.create(12345)
-            time_of_use_settings_response = await energy_site.time_of_use_settings(settings={"tou_settings": {"tariff_content_v2": {}}})
+            time_of_use_settings_response = await energy_site.time_of_use_settings(settings={})
             print(time_of_use_settings_response)
         except TeslaFleetError as e:
             print(e)
 
 asyncio.run(main())
 ```
 
+The top-level `get_tariff_periods` helper resolves the current buy and sell
+rates from a raw `tariff_content_v2` object without making any API calls.
+`unwrap_tariff_v2` accepts the `site_info()` response envelope, the
+`tou_settings` write envelope, or a bare tariff object:
+
+```python
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+from tesla_fleet_api import get_tariff_periods, unwrap_tariff_v2
+
+site_info = await energy_site.site_info()
+tariff = unwrap_tariff_v2(site_info)
+site_timezone = ZoneInfo("<installation_time_zone from site_info>")
+now = datetime.now(site_timezone)
+resolution = get_tariff_periods(tariff, now, horizon_hours=24)
+```
+
+`now` must be timezone-aware and expressed in the site's local timezone because
+the tariff object does not carry its own timezone. A naive `now` raises
+`ValueError`. The result contains the current buy and sell rates, the current
+period's start, the next change, the currency, and (when `horizon_hours` is
+provided) a contiguous timeline of upcoming periods. Gaps in the buy schedule
+are preserved as one merged `TariffPeriod` with both rates set to `None`; the
+gap ends when the tariff resumes, or at the horizon deadline if it does not.
+The helper returns `None` when no tariff season covers `now`. Missing rates
+remain `None`, while a real zero price remains `0.0`.
+Null or malformed inputs passed to `unwrap_tariff_v2` raise `InvalidResponse`.
+This includes every accepted envelope or bare tariff object whose extracted
+tariff lacks either `seasons` or `energy_charges`.
+
 ## Device Commands
 
 Energy gateways (Powerwalls, etc.) support gRPC commands sent via `POST /api/1/energy_sites/{id}/command`. These are undocumented Tesla API endpoints that communicate directly with the gateway hardware. All device command methods require the `energy_cmds` scope.

tesla_fleet_api.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ tesla_fleet_api/__init__.py
 tesla_fleet_api/const.py
 tesla_fleet_api/exceptions.py
 tesla_fleet_api/py.typed
+tesla_fleet_api/tariff.py
 tesla_fleet_api/util.py
 tesla_fleet_api.egg-info/PKG-INFO
 tesla_fleet_api.egg-info/SOURCES.txt
@@ -91,8 +92,9 @@ tests/test_proto_compatibility.py
 tests/test_proto_coverage_lock.py
 tests/test_router.py
 tests/test_session_info_authentication.py
+tests/test_tariff.py
 tests/test_tesla_private_key.py
 tests/test_teslemetry_authorized_clients.py
 tests/test_teslemetry_gateway_address.py
 tests/test_tessie_vehicle_params.py
-tests/test_vehicle_image_state.py
+tests/test_vehicle_image_state.py

tesla_fleet_api/__init__.py

@@ -4,6 +4,13 @@
 __version__ = "1.7.7"
 
 from tesla_fleet_api.const import Region, is_valid_region
+from tesla_fleet_api.tariff import (
+    TariffPeriod,
+    TariffRate,
+    TariffResolution,
+    get_tariff_periods,
+    unwrap_tariff_v2,
+)
 from tesla_fleet_api.tesla.bluetooth import TeslaBluetooth
 from tesla_fleet_api.tesla.fleet import TeslaFleetApi
 from tesla_fleet_api.tesla.oauth import TeslaFleetOAuth
@@ -13,12 +20,17 @@
 
 __all__ = [
     "Region",
+    "TariffPeriod",
+    "TariffRate",
+    "TariffResolution",
     "TeslaFleetApi",
     "TeslaBluetooth",
     "TeslaFleetOAuth",
     "Teslemetry",
     "Tessie",
     "firmware_at_least",
     "firmware_compare",
+    "get_tariff_periods",
     "is_valid_region",
+    "unwrap_tariff_v2",
 ]