feat: well-production resource + tests; scrub committed API key (#32)

[karlwaldman]

Closes #32.

What

1. New client.wellProduction resource (src/resources/well-production.ts)

Typed coverage for all seven /v1/well-production* endpoints:

Method	Endpoint
summary()	GET /v1/well-production
states({ period? })	GET /v1/well-production/states
stateDetail(code, { start_date?, end_date? })	GET /v1/well-production/states/:state_code
wellDetail(apiNumber)	GET /v1/well-production/wells/:api_number
topProducers({ state_code?, limit?, months? })	GET /v1/well-production/top-producers
cycleTime(filters?)	GET /v1/well-production/cycle-time
cycleTimeCohorts(filters?)	GET /v1/well-production/cycle-time/cohorts

Response types were written against live-captured envelopes (2026-07-13), not guessed. wellDetail() normalizes separator formats (42-477-31122-00-00) and validates 14 digits client-side, matching the server rule.

2. ei.wellPermits.latest() envelope fix (per #32 acceptance criteria)

The live API returns { well_permits: [...], meta: {...} }, not a single record. latest() now returns a typed WellPermitLatestResponse (with new LatestWellPermit nested-record type). The old WellPermitRecord return type never matched runtime behavior.

3. README

New "Well Production" section with the beta coverage caveat: well-level data covers only regulator-collected states (AK/ND/NM/PA/TX today) — no complete-US well-level claim; EIA state aggregates are the comprehensive layer.

4. Security: committed credentials removed

example.ts, example-walk.ts (4x), example-commodities.ts, and qa_test.js contained a hardcoded API key. All literals are replaced with OILPRICEAPI_KEY env-var usage; examples exit with a clear message when unset and qa_test.js skips cleanly. The exposed key must be rotated server-side — it remains in git history.

5. Hygiene

• Added .github/dependabot.yml (weekly npm + github-actions, grouped dev-dep minor/patch).

Test evidence

npm test         → Test Files 29 passed (29); Tests 450 passed | 1 skipped (451)
npm run build    → clean (ESM + CJS)
npm run lint     → 0 errors (10 pre-existing warnings in alerts.ts)
npm audit        → 0 vulnerabilities

New suite tests/resources/well-production.test.ts (18 tests): endpoint paths/params for all 7 routes, envelope unwrapping from live fixtures, and negative paths — 403 ENTERPRISE_REQUIRED (the actual live entitlement gate), 402, 404 DATA_NOT_AVAILABLE (unsupported state + unknown well), 400 INVALID_PARAMETER, client-side ValidationErrors, and empty successful responses. All tests are mock-based and pass without an API key.

Live smoke (built dist/, production API):

summary top state: TX 2026-04
stateDetail TX count: 4 eia_api
cohorts group_by: quarter [ '2025-Q2', '2025-Q3' ]
ZZ -> NotFoundError 404
wellPermits.latest: 25 meta.count 25

Known backend issue (not SDK-fixable)

GET /v1/well-production/top-producers returns HTTP 500 on production (probed 2026-07-13). The SDK maps the controller's documented shape; needs a backend fix in oilpriceapi-api.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 53 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

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 reviews.

How do review limits work?

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

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, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9dc570bf-465a-43bf-b140-f19bb0967324

📥 Commits

Reviewing files that changed from the base of the PR and between fafd4ab and 64c0a08.

📒 Files selected for processing (13)

• .github/dependabot.yml
• README.md
• example-commodities.ts
• example-walk.ts
• example.ts
• qa_test.js
• src/client.ts
• src/index.ts
• src/resources/ei/index.ts
• src/resources/ei/well-permits.ts
• src/resources/well-production.ts
• tests/resources/ei.test.ts
• tests/resources/well-production.test.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/well-production-resource

---

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.}