Transport: per-request extra_headers is unreachable through any resource method #253

Summary

The documented per-request header feature (Idempotency-Key, X-Request-ID, distributed-tracing headers — #220 polish) can only be set by bypassing the public resource API and calling client._transport.request(...) directly — i.e., reaching into a private attribute. The most common use case — a per-order Idempotency-Key on orders.create_order — has no public path. The feature is effectively private despite being in the changelog as additive.

Location

• kalshi/_base_client.py:182-191 — transport request() signature accepts extra_headers
• kalshi/resources/_base.py:136-223 — none of _get/_post/_post_json/_put/_delete/_delete_with_body/_delete_with_body_json forward it

Evidence

# transport signature (sync + async):
def request(self, method, path, *, params=None, json=None, content=None,
            headers=None, extra_headers=None) -> httpx.Response: ...

# resource base — none of the helpers thread extra_headers:
def _post(self, path, *, params=None, json=None) -> dict[str, Any]:
    response = self._transport.request("POST", path, params=params, json=json)
    ...

Recommended fix

Either (a) thread extra_headers: dict[str, str] | None = None through SyncResource/AsyncResource helpers and through the resource methods that need it (at minimum orders.create, orders.batch_create, orders.cancel), or (b) document client._transport.request(..., extra_headers=...) as the supported escape hatch and rename it to a public client.raw_request / client.transport.

Severity & category

medium / api-design