fix: correct market response types (BREAKING CHANGE)

[harley-poly]

Changes

Correct sync and async markets.book() and markets.bbo() to return the marketData response envelope, and settlement to return { "slug": str, "settlement": float }. Include the closed market state and nullable fields returned by the API.

Runtime responses are unchanged. Consumers using the previous declarations should read book/BBO data through marketData and settlement through the numeric settlement field. Add the consumer fixture to the existing mypy CI job.

Release compatibility

BREAKING CHANGE: Typed consumers must read book/BBO data through marketData, use slug and numeric settlement, and handle nullable market data fields. The README includes the migration example for sync and async clients.

The existing publish workflow classifies this as a major release (0.1.2 → 1.0.0). The PR title and final nonempty commit carry the marker for the configured merge, squash, and rebase defaults. Accept this version choice before merging and preserve BREAKING CHANGE in the final commit message.

Testing

• uv run pytest — 140 tests pass on Python 3.12 and 3.10, including sync/async populated/empty market data and settlement values 0, 0.5 and 1.
• uv run mypy polymarket_us tests/types — 33 files pass on both Python versions.
• uv run ruff check . and uv run ruff format --check . pass.
• uv build passes.
• git diff --check, migration example syntax, and publish classifier checks for default merge, squash, and rebase messages pass.
• The consumer fixture fails with 10 expected errors against the original declarations and passes with the correction.

Checklist

• Tests pass (pytest)
• Linting passes (ruff check .)
• Types check (mypy polymarket_us)

---

Note

Medium Risk
Corrects public TypedDict shapes in a breaking way for type-checked consumers, though runtime JSON and HTTP behavior are unchanged.

Overview
Aligns market endpoint typings with the JSON the API already returns, without changing runtime behavior.

markets.book() and markets.bbo() (sync and async) are now typed as GetMarketBookResponse / GetMarketBBOResponse with a marketData wrapper instead of bare MarketBook / MarketBBO. MarketSettlement is updated to slug and a numeric settlement (replacing the old slug/price/timestamp fields). Nested types add MARKET_STATE_CLOSED, and nullable stats, transactTime, and BBO price fields for empty/closed markets.

CI mypy now checks tests/types, including a consumer fixture that exercises reading marketData and settlement. Market tests use pytest-httpx for sync/async wire-equality checks on populated and empty book/BBO payloads and settlement values 0, 0.5, and 1.

Typed callers who followed the previous declarations must use response["marketData"] for book/BBO and settlement["settlement"] for settlement price.

^{Reviewed by Cursor Bugbot for commit 62da7c5. Bugbot is set up for automated code reviews on this repo. Configure here.}