chore: pay down mypy typing-debt + param audit + live demo contract tests

[karlwaldman]

Summary

Hardens the Python SDK across three fronts: paying down mypy typing-debt, auditing request params against the real Rails controllers, and adding live demo-endpoint contract tests. No version bump.

Task 1 — mypy typing-debt paid down

Removed all 10 TODO(typing-debt) per-module mypy overrides by fixing the underlying type errors with proper annotations (not # type: ignore):

Module	What was wrong	Fix
oilpriceapi (__init__)	implicit-Optional default	api_key: Optional[str] = None
client	Optional[list]/tuple return, viz/last_exception types, Headers arg	proper generics + annotations
async_client	Optional[list], self._client = None typed None, response["data"] on union, untyped AsyncGenerator	annotated Optional[httpx.AsyncClient], narrowed with isinstance, AsyncGenerator[List[HistoricalPrice], None]
cli	duplicate main def + Callable.command	single main, exit-at-import fallback, typed commodity_list
telemetry	untyped _events, no_implicit_reexport import, kwargs dict	annotations + import from version module
prices	union-attr on get_multiple result	assert isinstance(prices, list)
alerts, analytics, data_sources, webhooks	Dict[str, str] inferred dicts	Dict[str, Any] annotations

Overrides removed: oilpriceapi, client, async_client, cli, telemetry, prices, alerts, analytics, data_sources, webhooks.

Overrides remaining (and why):

• oilpriceapi.* — package-wide annotation-completeness relaxation (no-untyped-def, no-any-return, no-untyped-call). This is the legitimate "SDK not yet fully annotated" debt, not real-bug codes. Out of scope to fully annotate every method here.
• oilpriceapi.models import-untyped — models.py optionally imports dateutil; the stub package isn't a runtime/CI dep, so this is a missing-stub finding, not a typing bug.

Task 2 — param-correctness audit (same bug class as the Node SDK)

Audited SDK params/paths against oilpriceapi-api/app/controllers/. Findings + fixes:

• analytics (confirmed Node bug class): SDK sent commodity/commodity1/commodity2/days, but analytics_controller.rb reads code/code1/code2/period. Fixed correlation (code1/code2/period), statistics/trend/forecast (code/period), performance (maps to controller range), and spread (the endpoint takes a named spread, not two codes — also added available_spreads()). Applied to the async analytics resource too.
• webhooks: controller permits status (active/inactive/paused), not boolean enabled. create/update now map enabled → status (sync + async).
• data_sources: controller does params.require(:data_source).permit(:status, scraper_config: {}) — SDK sent flat body with enabled/config. Now nests under data_source and maps enabled → status, config → scraper_config (sync + async).
• alerts: already correct — nests under price_alert with commodity_code/condition_operator/condition_value/enabled. No change.
• Paths for webhooks/data-sources/alerts/analytics all verified against config/routes.rb.

Added wire-param unit tests asserting the exact params sent (regression guards against the old keys).

Task 3 — live demo contract tests (no key needed)

New DemoResource (exposed as client.demo, also usable standalone with no API key) hitting GET /v1/demo/prices and /v1/demo/commodities.

Live tests live in tests/integration/test_demo_contract.py (marked live, excluded from the default unit gate via --ignore=tests/integration). They assert the real envelope {status, data:{prices|commodities, meta}}: 9 free-tier prices incl BRENT_CRUDE_USD ≈ $80, 442 commodities (meta.total == flattened catalog), and meta.free_commodities. Mocked unit tests cover the accessor in the default gate. Verified passing against the live API.

Gates (all green)

• mypy oilpriceapi/ --ignore-missing-imports → Success (40 files)
• ruff check oilpriceapi/ → clean
• pytest tests/ --ignore=tests/integration --ignore=tests/contract -m 'not slow' --cov=oilpriceapi → 249 passed, 9 skipped, coverage 57.38% (≥50)

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@karlwaldman, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 15 minutes and 43 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 961257d0-13b8-417a-b4b7-885dc55dbaf7

📥 Commits

Reviewing files that changed from the base of the PR and between 25c9d53 and 911ed0c.

📒 Files selected for processing (20)

• oilpriceapi/__init__.py
• oilpriceapi/async_client.py
• oilpriceapi/async_resources.py
• oilpriceapi/cli.py
• oilpriceapi/client.py
• oilpriceapi/resources/__init__.py
• oilpriceapi/resources/alerts.py
• oilpriceapi/resources/analytics.py
• oilpriceapi/resources/data_sources.py
• oilpriceapi/resources/demo.py
• oilpriceapi/resources/prices.py
• oilpriceapi/resources/webhooks.py
• oilpriceapi/telemetry.py
• pyproject.toml
• tests/integration/conftest.py
• tests/integration/test_demo_contract.py
• tests/unit/test_analytics_resource.py
• tests/unit/test_data_sources_resource.py
• tests/unit/test_demo_resource.py
• tests/unit/test_webhooks_resource.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/typing-and-contracts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}