Skip to content

Ship generic futures routes and permit-to-production flow - #65

Merged
karlwaldman merged 2 commits into
mainfrom
codex/sdk-contracts-20260811
Aug 11, 2026
Merged

Ship generic futures routes and permit-to-production flow#65
karlwaldman merged 2 commits into
mainfrom
codex/sdk-contracts-20260811

Conversation

@karlwaldman

@karlwaldman karlwaldman commented Aug 11, 2026

Copy link
Copy Markdown
Member

Summary

  • route futures codes and named helpers through instrument-generic aliases while preserving explicit legacy slug inputs
  • unwrap production-shaped well permit search results and document a coverage-gated permit-to-production flow
  • harden trusted publication with protected-main provenance and a checksummed artifact/publisher handoff
  • prepare patch release 1.2.2

Red-green proof

  • futures/README contract tests began red: 22 failures across venue paths and the missing coverage path
  • production-shaped { well_permits, meta } search regression was added before the unwrapping fix
  • release publisher test began red on the single privileged dependency-executing job
  • final local: 33 files / 469 passed / 1 skipped; release readiness 5/5

Verification

  • npm audit --audit-level=low: 0 vulnerabilities
  • npm run lint: green, zero warnings
  • npm run storefront:check: 36 public surfaces
  • npm run check:secrets: green
  • npm run build: ESM and CJS green
  • npm run snippets:check: 6/6 fixtures plus manifest tests
  • npm run smoke:package: exact packed ESM/CJS keyless production smoke green
  • workflow YAML parse and git diff --check: green

Closes the Node portions of OilpriceAPI/oilpriceapi-api#4175 and OilpriceAPI/oilpriceapi-api#3941.

Summary by CodeRabbit

  • New Features

    • Added Permit to Production guidance for well coverage, permit searches, API validation, and production details.
    • Added well-related package discovery keywords.
    • Introduced canonical futures identifiers for Brent, WTI, Gasoil, and EU carbon while preserving legacy aliases.
    • Improved well permit searches to support structured API responses.
  • Bug Fixes

    • Improved compatibility with varied permit response formats.
  • Documentation

    • Added release notes for version 1.2.2 and updated futures examples.

@coderabbitai

coderabbitai Bot commented Aug 11, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

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

Next review available in: 37 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

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 Plus

Run ID: b2868a84-7311-46cb-aa16-efc40d6c9417

📥 Commits

Reviewing files that changed from the base of the PR and between fa25730 and dd7256d.

📒 Files selected for processing (6)
  • CHANGELOG.md
  • README.md
  • src/resources/ei/well-permits.ts
  • tests/release-readiness.test.ts
  • tests/resources/ei.test.ts
  • tests/resources/futures-family.test.ts
📝 Walkthrough

Walkthrough

The release workflow now verifies and publishes immutable artifacts through dependent jobs. The release adds permit-to-production documentation, typed permit envelope handling, canonical futures slugs with legacy aliases, and version 1.2.2 metadata.

Changes

Release pipeline

Layer / File(s) Summary
Verify and prepare release artifacts
.github/workflows/publish.yml, package.json, src/version.ts, tests/release-readiness.test.ts
The workflow validates the release, runs checks, builds artifacts, creates signed metadata, and uploads checksummed files. Version assertions now target 1.2.2.
Publish the verified package
.github/workflows/publish.yml
The publish job verifies the artifact, publishes the exact tarball when needed, and confirms npm integrity and the latest tag.
Attach the release manifest
.github/workflows/publish.yml, CHANGELOG.md
The release-assets job verifies the artifact and uploads the snippet manifest. The changelog records the 1.2.2 release changes.

Permit-to-production API

Layer / File(s) Summary
Support typed permit search envelopes
src/resources/ei/well-permits.ts, tests/resources/ei.test.ts
Permit search now returns LatestWellPermit[] from raw arrays, data envelopes, or well_permits envelopes.
Document the permit-to-production path
README.md, package.json, tests/release-readiness.test.ts
The README documents coverage checks, permit searches, API number validation, production retrieval, and valid empty-result states. Package keywords expose the related capabilities.

Canonical futures slugs

Layer / File(s) Summary
Define canonical futures families
src/resources/futures.ts
The slug union and contract mappings now use canonical Brent, WTI, Gasoil, and EU carbon values while accepting legacy aliases.
Route futures helpers to canonical endpoints
src/resources/futures.ts
Named helpers and examples now use canonical slugs for futures family and price requests.
Validate canonical futures routing
tests/resources/futures-family.test.ts, tests/resources/futures.test.ts
Tests now assert canonical mappings, case-insensitive resolution, helper slugs, and venue-neutral request paths.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant verify
  participant ArtifactStore
  participant publish
  participant npmRegistry
  participant release_assets
  participant GitHubRelease
  verify->>ArtifactStore: upload signed package artifact and checksums
  publish->>ArtifactStore: download artifact
  publish->>publish: verify artifact checksum
  publish->>npmRegistry: publish exact npm tarball
  npmRegistry-->>publish: return package integrity and latest tag
  release_assets->>ArtifactStore: download artifact
  release_assets->>release_assets: verify artifact checksum
  release_assets->>GitHubRelease: upload snippet manifest
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly identifies the two primary product changes: generic futures routes and the permit-to-production flow.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/sdk-contracts-20260811

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

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
tests/resources/ei.test.ts (1)

252-267: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add coverage for all supported response shapes.

This test covers only the { well_permits: ... } envelope. Add cases for a raw LatestWellPermit[] response and a { data: LatestWellPermit[] } response to protect the other branches in EIWellPermitsResource.search.

Also applies to: 280-280

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/resources/ei.test.ts` around lines 252 - 267, Extend the well-permits
search tests around the existing spy and client.ei.wellPermits.search call to
cover both remaining response shapes: a raw LatestWellPermit[] payload and a {
data: LatestWellPermit[] } envelope. Assert each shape produces the expected
search results, while preserving the existing { well_permits: ... } coverage.
tests/resources/futures-family.test.ts (1)

147-162: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add regression cases for the remaining legacy aliases.

The implementation retains ice-brent, ice-wti, ice-gasoil, and eua-carbon. These tests cover only the first two aliases across the file. Add parameterized cases for ice-gasoil and eua-carbon, including uppercase inputs, to protect legacy compatibility.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/resources/futures-family.test.ts` around lines 147 - 162, Extend the
futures family resolution tests around resolveFuturesFamilySlug with
parameterized regression cases for ice-gasoil and eua-carbon, asserting their
expected slugs and including uppercase input variants to verify case-insensitive
legacy alias support.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/resources/ei/well-permits.ts`:
- Line 328: Revert the search method’s return type and behavior to preserve the
existing WellPermitRecord[] API in async search(query: WellPermitSearchQuery).
Defer LatestWellPermit[] to a major release or expose it through a separate
method without changing search compatibility.

---

Nitpick comments:
In `@tests/resources/ei.test.ts`:
- Around line 252-267: Extend the well-permits search tests around the existing
spy and client.ei.wellPermits.search call to cover both remaining response
shapes: a raw LatestWellPermit[] payload and a { data: LatestWellPermit[] }
envelope. Assert each shape produces the expected search results, while
preserving the existing { well_permits: ... } coverage.

In `@tests/resources/futures-family.test.ts`:
- Around line 147-162: Extend the futures family resolution tests around
resolveFuturesFamilySlug with parameterized regression cases for ice-gasoil and
eua-carbon, asserting their expected slugs and including uppercase input
variants to verify case-insensitive legacy alias support.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0df57c0f-4b7f-486e-b709-bafbd7bff42d

📥 Commits

Reviewing files that changed from the base of the PR and between 16acd43 and fa25730.

⛔ Files ignored due to path filters (1)
  • package-lock.json is excluded by !**/package-lock.json
📒 Files selected for processing (11)
  • .github/workflows/publish.yml
  • CHANGELOG.md
  • README.md
  • package.json
  • src/resources/ei/well-permits.ts
  • src/resources/futures.ts
  • src/version.ts
  • tests/release-readiness.test.ts
  • tests/resources/ei.test.ts
  • tests/resources/futures-family.test.ts
  • tests/resources/futures.test.ts

Comment thread src/resources/ei/well-permits.ts Outdated
@karlwaldman
karlwaldman merged commit 93baf77 into main Aug 11, 2026
8 checks passed
@karlwaldman
karlwaldman deleted the codex/sdk-contracts-20260811 branch August 11, 2026 15:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant