fix: Order.type rename, BASE_URL validation, Retry-After NaN/negative guard (#112)

* fix(orders, events, series): rename Order.type, normalize bool query params

F-N-03: Order.type was leftover from the pre-v0.8.0 CreateOrderRequest.type
field. The spec's Order schema does still include a `type` enum on
responses, so rename SDK-side to `order_type` (validation alias accepts
the wire `type`) — same builtin-shadow rationale as milestone_type,
target_type, and incentive_type elsewhere.

F-N-08: events.py and series.py built bool query params inline with
`"true" if x else None`, which silently drops explicit False. Replace
with the documented `_bool_param(...)` helper so callers can opt out
(False -> "false"). Mechanical, matches markets.py / live_data.py.

Closes #91

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(config): validate KALSHI_API_BASE_URL scheme and host

Reject base_url with a non-http(s) scheme or http:// pointing at a
remote host. The previous config accepted any string, so an attacker
who could write to a process's environment (docker run -e, CI variable,
shell history) could redirect every authenticated request — and the
KALSHI-ACCESS-KEY header and request signature — to an endpoint they
control.

- https://* with a known Kalshi host (production, demo): silent.
- https://* with any other host: warn (keeps legitimate proxy use
  cases working but surfaces awareness).
- http://localhost, 127.0.0.1, ::1: allowed (local mocks, tests).
- http://<remote host>: ValueError at config construction.
- non-http(s) scheme or missing host: ValueError.

Closes #94

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(retry): reject negative, NaN, and infinite Retry-After values

Retry-After was parsed with bare float() and used straight in
``min(retry_after, retry_max_delay)``. Three failure modes the cap
didn't cover:

- ``Retry-After: -1`` -> ``min(-1, 30) = -1`` -> ``time.sleep(-1)`` is
  a POSIX no-op; the client busy-loops the server-controlled retry.
- ``Retry-After: nan`` -> ``min(nan, 30) = nan`` -> ``time.sleep(nan)``
  raises ValueError outside the documented retry pathway.
- ``Retry-After: inf`` -> would survive the cap math but had no test.

Reject all three at parse time and fall back to computed backoff.
HTTP-date format still falls through unchanged.

Closes #96

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: address #112 bot feedback (ws_base_url, CHANGELOG, comment trim)

Per code review on PR #112:

- Validate ws_base_url with the same scheme/host rules as base_url.
  WebSocket connect carries KALSHI-ACCESS-KEY too, so plaintext-to-remote
  is the same credential-leakage surface as #94. Generalized
  _validate_base_url -> _validate_url(secure=, plaintext=) so http/https
  and ws/wss share the rule.
- CHANGELOG.md: added [Unreleased] Breaking section for Order.type ->
  Order.order_type. Version bump (v1.2 vs v2.0) still deferred to
  release cut, but the entry now exists.
- _base_client.py: trimmed the 5-line Retry-After comment block to one
  line per CLAUDE.md style guide.
- Added TestWsBaseUrlValidation (+6 tests).

Deferred (not addressed):
- Optional @Property def type(self) deprecation shim. User explicitly
  picked the clean-break rename earlier.
- Pre-existing Order lacks model_config; outside this PR's scope, will
  open a follow-up issue.
- Cosmetic host -> url_host test variable rename; low value.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(retry): honor Retry-After: 0 end-to-end through transport

Per second-pass bot review on #112: the prior commit kept Retry-After: 0
on the error object, but transport's "if error.retry_after:" check
dropped 0 as falsy and fell through to backoff. Switched to
"is not None" in both sync and async transport. Added regression
tests that monkeypatch time.sleep / asyncio.sleep and assert the
delay is exactly 0.0 (not the backoff fallback).

Also addressed:
- config._validate_url docstring trimmed to one line (CLAUDE.md).
- Called via KalshiConfig._validate_url(...) rather than self.
  (staticmethod-through-self hides that no instance state is used).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: TexasCoding

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to kalshi-sdk will be documented in this file.
 
+## [Unreleased]
+
+### Breaking
+
+- **`Order.type` renamed to `Order.order_type`.** Wire format is unchanged
+  (`validation_alias=AliasChoices("type", "order_type")` accepts both names on
+  deserialization), but any user code reading `.type` on an `Order` instance
+  must migrate to `.order_type`. Rationale: matches the project's existing
+  builtin-shadow-avoidance convention (`milestone_type`, `target_type`,
+  `incentive_type`). Spec v3.13.0 still defines `type` as required, so the
+  field is preserved on the wire — only the Python attribute name changed
+  (#91).
+
+  ```python
+  # Before
+  order = client.portfolio.orders.get(order_id="...")
+  print(order.type)  # AttributeError after upgrade
+
+  # After
+  print(order.order_type)
+  ```
+
+  Version-bump decision (v1.2 vs v2.0) deferred to release cut.
+
 ## 1.1.0 — 2026-05-16
 
 Post-1.0 enhancements and polish. 17 issues closed across four parallel waves of

kalshi/_base_client.py

@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import logging
+import math
 import random
 import time
 from typing import Any
@@ -59,6 +60,9 @@ def _map_error(response: httpx.Response) -> KalshiError:
         if retry_after:
             try:
                 retry_after_val = float(retry_after)
+                # Reject non-finite/negative: NaN crashes time.sleep, negative busy-loops.
+                if retry_after_val < 0 or not math.isfinite(retry_after_val):
+                    retry_after_val = None
             except ValueError:
                 retry_after_val = None  # HTTP-date format, fall back to computed backoff
         return KalshiRateLimitError(
@@ -168,8 +172,12 @@ def request(
             if not should_retry:
                 raise error
 
-            # Use Retry-After header if available for 429
-            if isinstance(error, KalshiRateLimitError) and error.retry_after:
+            # Use Retry-After header if available for 429.
+            # `is not None` — not truthy — so Retry-After: 0 ("retry immediately") is honored.
+            if (
+                isinstance(error, KalshiRateLimitError)
+                and error.retry_after is not None
+            ):
                 delay = min(error.retry_after, self._config.retry_max_delay)
             else:
                 delay = _compute_backoff(attempt, self._config)
@@ -282,7 +290,11 @@ async def request(
             if not should_retry:
                 raise error
 
-            if isinstance(error, KalshiRateLimitError) and error.retry_after:
+            # `is not None` so Retry-After: 0 ("retry immediately") is honored.
+            if (
+                isinstance(error, KalshiRateLimitError)
+                and error.retry_after is not None
+            ):
                 delay = min(error.retry_after, self._config.retry_max_delay)
             else:
                 delay = _compute_backoff(attempt, self._config)

kalshi/config.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import logging
 from dataclasses import dataclass, field
+from urllib.parse import urlparse
 
 PRODUCTION_BASE_URL = "https://api.elections.kalshi.com/trade-api/v2"
 DEMO_BASE_URL = "https://demo-api.kalshi.co/trade-api/v2"
@@ -14,6 +16,13 @@
 DEFAULT_MAX_RETRIES = 3
 DEFAULT_WS_MAX_RETRIES = 10
 
+_KNOWN_HOSTS = frozenset(
+    {"api.elections.kalshi.com", "demo-api.kalshi.co"}
+)
+_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+logger = logging.getLogger("kalshi")
+
 
 @dataclass(frozen=True)
 class KalshiConfig:
@@ -42,6 +51,41 @@ def __post_init__(self) -> None:
             object.__setattr__(self, "base_url", self.base_url.rstrip("/"))
         if self.ws_base_url.endswith("/"):
             object.__setattr__(self, "ws_base_url", self.ws_base_url.rstrip("/"))
+        KalshiConfig._validate_url(self.base_url, "base_url", secure="https", plaintext="http")
+        KalshiConfig._validate_url(self.ws_base_url, "ws_base_url", secure="wss", plaintext="ws")
+
+    @staticmethod
+    def _validate_url(url: str, field_name: str, *, secure: str, plaintext: str) -> None:
+        """Reject URLs that would expose credentials (bad scheme or plaintext-to-remote)."""
+        parsed = urlparse(url)
+        scheme = parsed.scheme.lower()
+        host = (parsed.hostname or "").lower()
+
+        if scheme not in (secure, plaintext):
+            raise ValueError(
+                f"KalshiConfig.{field_name} must use {secure}:// or {plaintext}://, "
+                f"got scheme={scheme!r} (url={url!r})"
+            )
+        if not host:
+            raise ValueError(
+                f"KalshiConfig.{field_name} is missing a host: {url!r}"
+            )
+        if scheme == plaintext and host not in _LOCAL_HOSTS:
+            raise ValueError(
+                f"KalshiConfig.{field_name} must use {secure}:// for non-loopback "
+                f"hosts; {plaintext}:// is only allowed for {sorted(_LOCAL_HOSTS)} "
+                f"(url={url!r}). Plaintext to a remote host would "
+                f"expose the KALSHI-ACCESS-KEY header and request signature."
+            )
+        if host not in _KNOWN_HOSTS and host not in _LOCAL_HOSTS:
+            logger.warning(
+                "KalshiConfig.%s host %r is not a known Kalshi "
+                "endpoint (%s). Requests will be signed and sent there "
+                "with your API key — verify this is intentional.",
+                field_name,
+                host,
+                sorted(_KNOWN_HOSTS),
+            )
 
     @classmethod
     def production(cls, **kwargs: object) -> KalshiConfig:

kalshi/models/orders.py

@@ -44,7 +44,14 @@ class Order(BaseModel):
     status: str | None = None
     side: str | None = None
     is_yes: bool | None = None
-    type: str | None = None
+    # Spec field is named ``type`` (enum: limit, market). Renamed to
+    # ``order_type`` on the SDK side to avoid shadowing the Python builtin —
+    # same rationale as milestone_type / target_type / incentive_type
+    # elsewhere. The wire still sends ``type``; validation alias accepts both.
+    order_type: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("type", "order_type"),
+    )
     yes_price: DollarDecimal | None = Field(
         default=None,
         validation_alias=AliasChoices("yes_price_dollars", "yes_price"),

kalshi/resources/events.py

@@ -7,7 +7,7 @@
 
 from kalshi.models.common import Page
 from kalshi.models.events import Event, EventMetadata, EventStatusLiteral
-from kalshi.resources._base import AsyncResource, SyncResource, _params
+from kalshi.resources._base import AsyncResource, SyncResource, _bool_param, _params
 
 # Shared param builders (issue #46).
 
@@ -26,8 +26,8 @@ def _list_events_params(
     return _params(
         status=status,
         series_ticker=series_ticker,
-        with_nested_markets="true" if with_nested_markets else None,
-        with_milestones="true" if with_milestones else None,
+        with_nested_markets=_bool_param(with_nested_markets),
+        with_milestones=_bool_param(with_milestones),
         min_close_ts=min_close_ts,
         min_updated_ts=min_updated_ts,
         limit=limit,
@@ -46,7 +46,7 @@ def _list_multivariate_events_params(
     return _params(
         series_ticker=series_ticker,
         collection_ticker=collection_ticker,
-        with_nested_markets="true" if with_nested_markets else None,
+        with_nested_markets=_bool_param(with_nested_markets),
         limit=limit,
         cursor=cursor,
     )
@@ -136,7 +136,7 @@ def get(
         with_nested_markets: bool = False,
     ) -> Event:
         params = _params(
-            with_nested_markets="true" if with_nested_markets else None,
+            with_nested_markets=_bool_param(with_nested_markets),
         )
         data = self._get(f"/events/{event_ticker}", params=params)
         return Event.model_validate(data.get("event", data))
@@ -230,7 +230,7 @@ async def get(
         with_nested_markets: bool = False,
     ) -> Event:
         params = _params(
-            with_nested_markets="true" if with_nested_markets else None,
+            with_nested_markets=_bool_param(with_nested_markets),
         )
         data = await self._get(f"/events/{event_ticker}", params=params)
         return Event.model_validate(data.get("event", data))

kalshi/resources/series.py

@@ -11,7 +11,7 @@
     Series,
     SeriesFeeChange,
 )
-from kalshi.resources._base import AsyncResource, SyncResource, _params
+from kalshi.resources._base import AsyncResource, SyncResource, _bool_param, _params
 
 # Shared param builders (issue #46).
 
@@ -27,8 +27,8 @@ def _list_series_params(
     return _params(
         category=category,
         tags=tags,
-        include_product_metadata="true" if include_product_metadata else None,
-        include_volume="true" if include_volume else None,
+        include_product_metadata=_bool_param(include_product_metadata),
+        include_volume=_bool_param(include_volume),
         min_updated_ts=min_updated_ts,
     )
 
@@ -40,7 +40,7 @@ def _fee_changes_params(
 ) -> dict[str, Any]:
     return _params(
         series_ticker=series_ticker,
-        show_historical="true" if show_historical else None,
+        show_historical=_bool_param(show_historical),
     )
 
 
@@ -98,7 +98,7 @@ def get(
         include_volume: bool | None = None,
     ) -> Series:
         params = _params(
-            include_volume="true" if include_volume else None,
+            include_volume=_bool_param(include_volume),
         )
         data = self._get(f"/series/{series_ticker}", params=params)
         return Series.model_validate(data.get("series", data))
@@ -188,7 +188,7 @@ async def get(
         include_volume: bool | None = None,
     ) -> Series:
         params = _params(
-            include_volume="true" if include_volume else None,
+            include_volume=_bool_param(include_volume),
         )
         data = await self._get(f"/series/{series_ticker}", params=params)
         return Series.model_validate(data.get("series", data))

tests/test_async_client.py

@@ -71,6 +71,31 @@ async def test_get_retries_on_429(self, transport: AsyncTransport) -> None:
         assert resp.status_code == 200
         assert route.call_count == 2
 
+    @respx.mock
+    @pytest.mark.asyncio
+    async def test_429_retry_after_zero_is_honored_end_to_end(
+        self, transport: AsyncTransport, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # Async counterpart of the sync regression: `is not None` keeps Retry-After: 0.
+        sleeps: list[float] = []
+
+        async def fake_sleep(d: float) -> None:
+            sleeps.append(d)
+
+        # _base_client imports asyncio inside the method, so patch the module attr directly.
+        monkeypatch.setattr("asyncio.sleep", fake_sleep)
+        respx.get("https://test.kalshi.com/trade-api/v2/markets").mock(
+            side_effect=[
+                httpx.Response(429, headers={"Retry-After": "0"}, json={"message": "rl"}),
+                httpx.Response(200, json={"markets": []}),
+            ]
+        )
+        resp = await transport.request("GET", "/markets")
+        assert resp.status_code == 200
+        assert sleeps == [0.0], (
+            f"Expected one sleep of 0.0s honoring Retry-After: 0, got {sleeps!r}"
+        )
+
     @respx.mock
     @pytest.mark.asyncio
     async def test_get_retries_on_500(self, transport: AsyncTransport) -> None: