release: v1.1.0 (#76)

TexasCoding · web-flow · commit 0a3fb23580b3 · 2026-05-16T21:41:44.000-05:00
* release: v1.1.0 Post-1.0 enhancements and polish. 17 issues closed across four parallel waves of work. Bump: - pyproject.toml version 1.0.0 → 1.1.0 - kalshi.__version__ 1.0.0 → 1.1.0 Docs: - CHANGELOG.md gets a comprehensive `## 1.1.0 — 2026-05-16` entry covering Added / Changed / Fixed / Test infrastructure / Infrastructure sections, the mypy-only breaking changes (Page TypeVar bound + Literal enum kwargs), and coverage stats. - ROADMAP.md updated — v1.1 feature-complete; only the two deferred / blocked issues remain (#45 prod creds, #53 nested $ref). - README.md surfaces v1.1 features: model-first `request=` overload, DataFrame integration, `kalshi.testing` mock transport, docs site link. Channel count corrected from 12 → 11 to match `CLAUDE.md` and the AsyncAPI spec. - AGENTS.md / CLAUDE.md gitnexus counts refreshed to the v1.1 indexed state (5819 symbols, 12421 relationships, 236 execution flows). Per `docs/RELEASING.md`, the next step is `git tag v1.1.0 && git push origin v1.1.0` — the release workflow will extract the CHANGELOG section, build sdist + wheel, publish to PyPI via OIDC trusted publisher (gated by the `pypi` environment reviewer), and create a GitHub Release with the extracted body and artifacts attached. * release: address PR #76 review — fix doc inconsistencies - CHANGELOG.md "Coverage at 1.1.0": - Source files 75 → 76 (matches `uv run mypy kalshi/` output) - Endpoints 90 → 89 (verified: 89 verb,path pairs across 77 paths) - Test count reworded as "1407 unit tests passing (1455 collected, 48 skipped)" so the framing matches the actual pytest output and matches the Verified section of the PR body - ROADMAP.md v1.0 shipped entry: "12 WS message types" → "11 WS channels" so the WS count is internally consistent across all docs (CLAUDE.md, README, AsyncAPI spec all say 11 channels) - README.md: revert 90 → 89 endpoints. v1.1 did not add a REST endpoint; the original 89 count from v1.0 is still correct - CLAUDE.md Testing section: stale "917 tests" → current "1455 collected (1407 passing, 48 skipped without live credentials)" - CLAUDE.md tree comment "(827 total)" dropped — structural overview doesn't need a count that drifts with every PR Verified: ruff/mypy untouched; the changes are doc-only.
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,7 +1,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **kalshi-python-sdk** (5324 symbols, 11635 relationships, 161 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **kalshi-python-sdk** (5819 symbols, 12421 relationships, 236 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,164 @@
 
 All notable changes to kalshi-sdk will be documented in this file.
 
+## 1.1.0 — 2026-05-16
+
+Post-1.0 enhancements and polish. 17 issues closed across four parallel waves of
+work. No breaking changes to runtime behavior; two mypy-level type-system
+tightenings are called out below.
+
+### Added
+
+- **Model-first request API.** Every POST/PUT/DELETE-with-body resource method
+  now accepts a pre-built request model as an alternative to individual kwargs.
+  Backward-compatible — the existing kwarg form continues to work unchanged
+  (#56).
+
+  ```python
+  client.orders.amend(request=AmendOrderRequest(order_id=..., yes_price=...))
+  client.orders.amend(order_id=..., yes_price=...)  # also works
+  ```
+
+  Each method has typed `@overload` stubs (32 methods × 2 = 64 stubs) so mypy
+  catches misuse at type-check time, not runtime.
+
+- **DataFrame integration.** `Page[T]` gained `.to_dataframe()` and
+  `.to_polars()` methods with optional dependency extras (#12):
+
+  ```bash
+  pip install 'kalshi-sdk[pandas]'   # or [polars] or [all]
+  ```
+
+  ```python
+  page = client.markets.list(limit=100)
+  df = page.to_dataframe()
+  ```
+
+  Lazy imports; `Decimal` and `datetime` preserved as native types via
+  `model_dump(mode="python")`.
+
+- **Record / replay mock transport** (`kalshi.testing`) for offline integration
+  testing (#13). `RecordingTransport` proxies real calls and saves
+  request/response pairs as JSON; `ReplayTransport` serves the fixtures with
+  no network. Sync and async transports both supported; signature/timestamp
+  headers are excluded from fingerprinting so signatures can drift between
+  record and replay.
+
+  ```python
+  with KalshiClient.from_env(transport=RecordingTransport("fixtures")) as c:
+      c.exchange.status()  # records once
+
+  with KalshiClient(transport=ReplayTransport("fixtures")) as c:
+      c.exchange.status()  # offline replay
+  ```
+
+- **Typed `Literal` aliases for fixed-enum kwargs** (#50). 13 new aliases
+  exported from `kalshi` and `kalshi.models`: `SideLiteral`, `ActionLiteral`,
+  `TimeInForceLiteral`, `SelfTradePreventionTypeLiteral`, `OrderStatusLiteral`,
+  `EventStatusLiteral`, `MarketStatusLiteral`, `MveFilterLiteral`,
+  `MveHistoricalFilterLiteral`, `MultivariateCollectionStatusLiteral`,
+  `IncentiveProgramStatusLiteral`, `IncentiveProgramTypeLiteral`,
+  `SettlementStatusLiteral`. mypy now catches typos in resource kwargs at
+  authoring time.
+
+- **MkDocs documentation site** (#14, #57). Material theme + mkdocstrings;
+  Getting Started, Authentication, WebSockets, Resources, Errors, Migration
+  guides plus auto-generated API reference. GitHub Pages deploy workflow at
+  `.github/workflows/docs.yml`.
+
+- **Constructor-variant integration tests** (#54). Exercises every supported
+  `KalshiClient` construction path against the demo API (`from_env`,
+  `key_id + private_key_path`, in-memory PEM string, pre-built `KalshiAuth`,
+  `demo=True`). Includes an async sibling test to catch signing-path drift.
+
+- **Per-method auth guards on `markets.orderbook`** (#49). Spec walk confirmed
+  this was the only public-resource GET endpoint missing `_require_auth()`;
+  unauthenticated callers now get a clear `AuthRequiredError` instead of a
+  confusing 401 from Kalshi.
+
+### Changed
+
+- **Sync/async dedup refactor** (#46). Extracted shared body-builder,
+  query-param-builder, and response-parser helpers across 13 resource modules.
+  Dispatcher logic and request-model construction now exist once per
+  method-pair instead of twice. Sync/async signatures, `@overload` stubs, and
+  the `async for item in client.markets.list_all():` ergonomic are all
+  preserved.
+
+- **Async `OrdersResource.batch_cancel` routed through shared
+  `_delete_with_body` helper** (#47). Previously called the transport directly,
+  bypassing the sync path's helper; any future retry / error-mapping change to
+  the helper now applies to both transports symmetrically.
+
+- **Sync `test_list_all` iteration idiom standardized** (#48). Sync tests now
+  use the same manual-counter loop as their async siblings; cosmetic only.
+
+### Fixed
+
+- **Async `multivariate.lookup_tickers` 204 spec-drift guard** (#72). Sync had
+  a clear `RuntimeError("spec drift: ...")` on an unexpected 204; async would
+  surface a confusing `TypeError` from `model_validate(None)`. Extracted a
+  shared `_parse_lookup_tickers_response` helper so both paths share the
+  guard.
+
+### Test infrastructure
+
+- **Typed `ExclusionKind`** discriminator on contract drift exclusions (#51).
+  Replaces the free-text `reason` substring matching in
+  `test_exclusion_map_is_current` with explicit
+  `Literal["body_param", "spec_deprecated", "paginator_handled",
+  "wire_normalization", "kwarg_rename"]` classification. All 47 existing
+  exclusions reclassified.
+
+- **Nested-model body-drift detection** (#52). The drift test now recurses
+  into nested `BaseModel` fields (e.g. `TickerPair` inside
+  `CreateMarketInMultivariateEventCollectionRequest.selected_markets`).
+  `TickerPair.extra="allow"` intentionally preserved because `LookupPoint`
+  responses echo provider keys; the existing pin test documents the carve-out.
+
+- **`kwarg_rename` `ExclusionKind`** split out of `wire_normalization` (#68).
+  Python-naming-hygiene renames (`milestone_type`, `target_type`,
+  `incentive_type` — spec field `type` shadows the builtin) are now
+  classified separately from wire-format normalization.
+
+### Infrastructure
+
+- **Weekly OpenAPI + AsyncAPI spec sync CI** (#16). Cron + manual dispatch
+  workflow snapshots both specs, regenerates models, runs ruff / mypy /
+  pytest, opens a PR with version + endpoint diff if any changes detected.
+  Third-party actions pinned to commit SHAs because the workflow holds
+  `contents: write` + `pull-requests: write`. Concurrency-guarded against
+  same-branch races.
+
+- **Nightly integration CI** against the demo API (#55). Secret-gated, skips
+  cleanly on forks, dedupes failure issues by stable title.
+
+### mypy-only breaking changes
+
+These tighten types without changing runtime behavior. Existing valid calls are
+unaffected; the type system will now reject calls that would have failed at
+runtime anyway (or that were always wrong but mypy couldn't see it).
+
+- `Page[T]` TypeVar tightened from `TypeVar("T")` to
+  `TypeVar("T", bound=BaseModel)`. Matches the bound already used inside
+  `kalshi/resources/_base.py` and the actual usage pattern across the SDK
+  (every concrete `Page[X]` parameterizes with a `BaseModel` subclass).
+- Resource-method kwargs for the 13 enum fields above are now `Literal[...]`
+  instead of `str | None`. Callers passing arbitrary strings (typos, in-flight
+  variable values) now fail at mypy-check time.
+
+### Coverage at 1.1.0
+
+- 89/89 REST endpoints implemented (sync + async); auth-guard audit complete
+  across public resources.
+- 11 WebSocket channels with sequence-gap detection, configurable backpressure,
+  and automatic reconnection.
+- **1407 unit tests passing** (1455 collected, 48 skipped — up from 899 at
+  1.0.0), mypy `--strict` clean (76 source files), ruff clean.
+- Drift tests now detect query/path/body/WS-payload schema drift _and_ nested
+  body-model drift.
+- Optional extras: `pandas`, `polars`, `all`, `docs`.
+
 ## 1.0.0 — 2026-05-10
 
 First stable release. No behavioral changes from 0.15.0 — this release marks
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -79,7 +79,7 @@ tests/
   _contract_support.py     # Contract test helpers
   integration/             # Live API integration tests
   ws/                      # WebSocket tests
-  test_*.py                # Per-resource + per-feature tests (827 total)
+  test_*.py                # Per-resource + per-feature tests
 ```
 
 ## Key conventions
@@ -116,7 +116,7 @@ tests/
 
 ## Testing
 
-- pytest + pytest-asyncio + respx (httpx mock); 917 tests.
+- pytest + pytest-asyncio + respx (httpx mock); 1455 tests collected (1407 passing, 48 skipped without live credentials).
 - Use `respx.mock` for HTTP mocking. Generate test RSA keys via conftest.py fixtures.
 - New function → write a test. Bug fix → write a regression test. New error path → write a test that triggers it.
 
@@ -144,7 +144,7 @@ Reference issues from PRs via `Closes #N` so the issue closes on merge.
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **kalshi-python-sdk** (5324 symbols, 11635 relationships, 161 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **kalshi-python-sdk** (5819 symbols, 12421 relationships, 236 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 
diff --git a/README.md b/README.md
@@ -7,11 +7,15 @@ A professional, spec-first Python SDK for the [Kalshi](https://kalshi.com) predi
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Type checked: mypy strict](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy.readthedocs.io/)
 
-- **Full coverage** of the Kalshi REST API (89 endpoints across 19 resources) and WebSocket API (12 message types).
+- **Full coverage** of the Kalshi REST API (89 endpoints across 19 resources) and WebSocket API (11 channels).
 - **Sync and async** clients sharing one transport — no thread-pool wrapping.
-- **Typed end-to-end**: Pydantic v2 models, `mypy --strict` clean, ships `py.typed`.
+- **Typed end-to-end**: Pydantic v2 models, `mypy --strict` clean, ships `py.typed`. `Literal` types on fixed-enum kwargs.
 - **Spec-aligned with drift guards**: hard-fail contract tests catch query, body, and WebSocket payload drift on every commit.
 - **Safe defaults**: only idempotent verbs (`GET`/`HEAD`/`OPTIONS`) retry; `POST`/`DELETE` never retry to avoid duplicate orders or cancels.
+- **DataFrame-ready**: optional `pandas` / `polars` extras for analysis workflows.
+- **Offline-testable**: record/replay mock transport (`kalshi.testing`) for SDK consumers building integration tests.
+
+📖 Full documentation: <https://texascoding.github.io/kalshi-python-sdk/>
 
 ## Install
 
@@ -120,6 +124,19 @@ with KalshiClient.from_env() as client:
 Prices are decimal dollars (e.g. `"0.65"`) per the Kalshi spec. Internally
 the SDK uses `Decimal` via the `DollarDecimal` type — never `float`.
 
+Every POST/PUT/DELETE-with-body method also accepts a pre-built request model
+as an alternative to individual kwargs (useful for programmatic order
+construction):
+
+```python
+from kalshi import CreateOrderRequest
+
+client.orders.create(request=CreateOrderRequest(
+    ticker="EXAMPLE-25-T", side="yes", action="buy",
+    count=10, yes_price="0.65",
+))
+```
+
 ## WebSocket streaming
 
 ```python
@@ -140,7 +157,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-Available channels: `ticker`, `trade`, `orderbook_delta`, `fill`,
+Available channels (11): `ticker`, `trade`, `orderbook_delta`, `fill`,
 `market_positions`, `user_orders`, `order_group`, `market_lifecycle`,
 `multivariate`, `multivariate_lifecycle`, `communications`.
 
@@ -213,10 +230,46 @@ for market in client.markets.list_all(status="open"):
     ...
 ```
 
+`Page[T]` also converts to a DataFrame when the optional extras are installed:
+
+```bash
+pip install 'kalshi-sdk[pandas]'   # or [polars] or [all]
+```
+
+```python
+df = client.markets.list(status="open", limit=100).to_dataframe()
+# Decimal and datetime preserved as native types in object columns.
+```
+
+## Testing against the SDK (no live API)
+
+For SDK consumers who want offline integration tests, `kalshi.testing` ships
+record-and-replay transports:
+
+```python
+from kalshi import KalshiClient
+from kalshi.testing import RecordingTransport, ReplayTransport
+
+# Record once against the real demo API:
+with KalshiClient.from_env(transport=RecordingTransport("fixtures")) as c:
+    c.exchange.status()
+
+# Replay in tests — no network:
+with KalshiClient(transport=ReplayTransport("fixtures")) as c:
+    c.exchange.status()  # served from fixtures/GET_*.json
+```
+
+Fixtures are JSON; the fingerprint ignores `KALSHI-ACCESS-SIGNATURE` and
+`KALSHI-ACCESS-TIMESTAMP` so signature drift between record and replay does not
+break matching. **Always `.gitignore` the fixture directory when recording
+against an authenticated account** — fixtures contain the full response body
+(balances, positions, PII).
+
 ## Resources
 
 | | |
 |---|---|
+| **Documentation site** | https://texascoding.github.io/kalshi-python-sdk/ |
 | **Kalshi REST OpenAPI spec** | https://docs.kalshi.com/openapi.yaml |
 | **Kalshi WebSocket AsyncAPI spec** | https://docs.kalshi.com/asyncapi.yaml |
 | **Production base URL** | `https://api.elections.kalshi.com/trade-api/v2` |
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,12 +1,24 @@
 # Roadmap
 
-Active milestone: **[v1.1 — Post-1.0 enhancements and polish](https://github.com/TexasCoding/kalshi-python-sdk/milestone/1)**.
+**v1.1 is feature-complete** — see `CHANGELOG.md`. The remaining two issues in
+the [v1.1 milestone](https://github.com/TexasCoding/kalshi-python-sdk/milestone/1)
+are deferred and don't block a release:
 
-All planned and proposed work lives in [GitHub Issues](https://github.com/TexasCoding/kalshi-python-sdk/issues).
+- **#45** — verify the `json={}` Content-Type workaround under production
+  credentials. Blocked on prod-key access.
+- **#53** — resolve nested `$ref` pointers in the body-schema drift check.
+  Premature — the spec currently has no nested refs.
+
+Future work lives in [GitHub Issues](https://github.com/TexasCoding/kalshi-python-sdk/issues).
 File a new issue (or comment on an existing one) rather than editing this file.
 
 ## Shipped
 
-See `CHANGELOG.md` for release history. v1.0 (2026-05-10) marks the public API surface
-as stable — REST coverage is complete (89/89 endpoints), WebSocket dispatch covers all
-12 message types, and contract drift tests block CI on any spec divergence.
+See `CHANGELOG.md` for full release history.
+
+- **v1.1.0 (2026-05-16)** — model-first request API, DataFrame integration,
+  record/replay mock transport, MkDocs documentation site, `Literal` enum
+  kwargs, sync/async dedup refactor, weekly spec sync + nightly integration
+  CI workflows.
+- **v1.0.0 (2026-05-10)** — public API stable. 89/89 REST endpoints, 11 WS
+  channels, contract drift tests, PyPI trusted-publisher release pipeline.
diff --git a/kalshi/__init__.py b/kalshi/__init__.py
@@ -224,4 +224,4 @@
     "UserDataTimestamp",
 ]
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "kalshi-sdk"
-version = "1.0.0"
+version = "1.1.0"
 description = "A professional Python SDK for the Kalshi prediction markets API"
 readme = "README.md"
 license = { text = "MIT" }

Original file line number	Diff line number	Diff line change
`@@ -224,4 +224,4 @@`
`224`	`224`	`"UserDataTimestamp",`
`225`	`225`	`]`
`226`	`226`
`227`		`-__version__ = "1.0.0"`
	`227`	`+__version__ = "1.1.0"`