fix(ei): return the named collection EI methods promise (#107)

Every Energy Intelligence method typed `List[Dict[str, Any]]` returned
`response["data"]`, but the EI controllers put their records under a *named*
key inside `data`. `client.ei.rig_counts.by_basin()` returned
`{"report_date": ..., "basins": [...]}` where the signature and the docstring
example promised the basin list, so the documented
`for basin in basins: basin["count"]` iterated dict keys.

Verified live against https://api.oilpriceapi.com on 2026-09-13 with a
Scale-tier key: 27 methods across seven EI resources are wrong the same way,
in both the sync resources and `async_resources.py`.

- `unwrap_ei_collection` / `unwrap_ei_object` / `ei_data` in
  `oilpriceapi/resources/ei/_envelopes.py` are now the single place that knows
  the envelope shape. The per-method
  `if "data" in response: return response["data"]` is gone, and
  `unwrap_well_permit_search_response` keeps its name and its error message
  but delegates to the shared helper instead of carrying a second copy.
- A success body missing the named collection raises
  `OilPriceAPIError(code="MALFORMED_RESPONSE")` instead of handing back the
  envelope. An empty collection stays an empty list.
- `ei.well_permits.get()` / `ei.frac_focus.get()` return the record rather
  than its `{"well_permit": ...}` wrapper.
- `ei.forecasts.prices()` / `.production()` are typed `Dict[str, Any]`: both
  return a mapping keyed by commodity / series code, never a list.
- `ei.well_permits.latest()` / `ei.frac_focus.latest()` deliberately keep
  returning the envelope so their pagination and freshness counters stay
  reachable; their docstrings now say so.
- Docstring examples use the field names the API actually returns.

Tests drive the real client transport (respx over httpx), not a stubbed
resource, because the defect lives between the HTTP body and the return value.
Valid, empty, missing-collection, malformed-row, 401/403/429 and async parity
are covered, plus a source-level guard that every async EI method's return
expression matches its sync twin character for character.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015ao5paex73xXvuM424Libo

Author: karlwaldman

CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to the OilPriceAPI Python SDK will be documented in this file.
 
+## [Unreleased]
+
+### Fixed
+
+- **Energy Intelligence collection methods now return the collection they
+  promise (#107).** Every EI method typed `List[Dict[str, Any]]` returned
+  `response["data"]` -- but the EI controllers put their records under a *named*
+  key inside `data`. `client.ei.rig_counts.by_basin()` returned
+  `{"report_date": ..., "basins": [...]}` where the signature and the docstring
+  example promised the basin list, so the documented
+  `for basin in basins: basin["count"]` iterated dict *keys*. The same defect
+  ran through `by_state` (`states`), `historical` (`records`), OPEC
+  `by_country`/`historical`/`top_producers`, oil-inventory
+  `by_product`/`historical`, drilling-productivity
+  `duc_wells`/`by_basin`/`historical`/`trends`, forecast `historical`, and
+  every well-permit and frac-focus collection -- 27 methods, sync and async.
+  Each now returns the named list, and a success body missing that list raises
+  `OilPriceAPIError(code="MALFORMED_RESPONSE")` instead of handing back the
+  envelope. An empty collection is still an empty list.
+- **`ei.well_permits.get()` and `ei.frac_focus.get()` return the record, not its
+  wrapper.** Production nests these under `data.well_permit` /
+  `data.frac_focus_disclosure`, so the documented `permit["operator"]` raised
+  `KeyError`.
+- **`ei.forecasts.prices()` and `ei.forecasts.production()` are typed
+  `Dict[str, Any]`.** Both return a mapping keyed by commodity / series code,
+  never a list; the `List[Dict[str, Any]]` annotation was wrong from the start.
+  No behaviour change.
+- **Docstring examples across the EI resources now use the field names the API
+  actually returns** (`region`/`count`, not the invented `name`/`rig_count`),
+  verified live on 2026-09-13.
+
+### Changed
+
+- The per-method `if "data" in response: return response["data"]` repeated
+  through every EI resource is replaced by one shared helper
+  (`oilpriceapi/resources/ei/_envelopes.py`).
+  `unwrap_well_permit_search_response` keeps its name and its error message and
+  now delegates to it, so there is one unwrapping implementation rather than
+  two.
+
+**Behaviour change for callers who adapted to the bug:** code reading
+`by_basin()["basins"]`, `well_permits.list()["well_permits"]` or
+`well_permits.get(id)["well_permit"]` must drop that subscript. Code following
+the documented signature was broken before and works now. `ei.well_permits.latest()`
+and `ei.frac_focus.latest()` deliberately keep returning the envelope object so
+their pagination and freshness counters stay reachable.
+
 ## [1.14.0] - 2026-09-13
 
 ### Fixed
@@ -112,8 +159,6 @@ pass the value you want explicitly.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
-
 ## [1.12.6] - 2026-08-11
 
 ### Changed