Migrate Opower data reads from REST to GraphQL

[loganrosen]

Summary

Migrates Opower data reads from REST to GraphQL for:

• Bill-level cost/usage reads
• Interval usage/cost reads (day/hour/half-hour/quarter-hour)
• Realtime usage reads

REST fallback for bill reads has been removed.

Key implementation changes

src/opower/opower.py

• Added GraphQL bill-cost path via _async_get_bill_cost_reads()
• Added GraphQL interval path via _async_discover_service_point() + _async_get_graphql_interval_reads()
• Added client-side interval aggregation (_aggregate_interval_reads())
• Interval reads pipeline uses CostRead internally, extracting monetaryAmount from GraphQL when available (defaults to 0 when null)
• Updated public APIs:
  • async_get_cost_reads() — returns CostRead for both bill and sub-bill aggregate types
  • async_get_usage_reads() — returns UsageRead (converts from internal CostRead)
  • async_get_realtime_usage_reads() — returns UsageRead
• Removed obsolete REST read paths for interval/realtime data

src/opower/__main__.py

• CLI output includes usage_charges and current_amount for bill-level reads

tests/test_opower.py

• Added GraphQL fixture tests for bill parsing/filtering
• Added interval discovery/fetch/cache tests
• Added batching/discovery-failure/non-bill-cost tests
• Added timezone bucketing regression test
• Added monetaryAmount summation test for interval cost reads

Validation

• Unit tests: 41 passed
• pre-commit: clean on changed files
• Live ConEd smoke tests passed for day, hour, and bill
• Live-tested monetaryAmount field against ConEd — accepted by server but returns null (ConEd does not populate sub-bill cost data)

Known limitations

• Gas interval filter values are currently best-effort (units: [CCF], serviceQuantityIdentifier: [DELIVERED]).
• Electric/ConEd path is live-verified; gas GraphQL interval variants have not yet been live-validated.
• monetaryAmount is null for ConEd interval reads. Other utilities may populate it — we carry it through when available.

Part of #176

[tronikos]

I haven't looked at the code. I just ran it for my utility PG&E and have several issues:

• I got empty usage_charges and current_amount in the output.
• The provided_cost is always 0 for me which is not the case when calling the REST API.
• The consumption gives weird values. With aggregation set to day the REST API returns -10.1933 (I have solar and I'm returning to the grid) while the new API returns 6.9. With aggregation set to hour the consumption seem to match during the night (e.g. 0.5545 vs 0.554, note the less precision from the new API) but not during the day when I return to the grid. REST API has negative values while the new API has 0.
• When the daylight saving time began on March 8 I get no results from 4am to 6pm, that's a gap of 14 hours. With the REST API I have no gap.

[loganrosen]

Thanks for testing with PG&E, @tronikos! I've pushed fixes for all four issues:

1. Empty usage_charges/current_amount — these columns are now only shown for bill-level reads (they're always None for interval reads, so showing them was confusing).

2. provided_cost always 0 — for bill reads, provided_cost now falls back to usageCharges when currentAmount is null. Previously it was hardcoded to currentAmount which was null for some utilities.

3. Wrong consumption values (no negatives, different daily totals) — the parser was skipping interval reads where measuredAmount was null instead of including them as 0. This was dropping data points. They're now included with consumption=0. (Note: if PG&E's GraphQL endpoint genuinely doesn't return negative values for solar net metering, that would be a server-side difference from the REST API — I can't fix that on the client side. Worth checking if the raw GraphQL response contains negatives.)

4. 14-hour DST gap — two fixes here: (a) null reads are no longer dropped (see point 3 above), and (b) interval query batches now use local time with UTC offset instead of converting to UTC, matching the format used by the bill query. This avoids ambiguity at DST boundaries.

I've verified all three aggregation types (bill/day/hour) against ConEd, including across the March 8 DST transition — no gaps.

Would be great if you could re-test with PG&E to confirm these fix the issues on your end!