fix(models): match live server for AccountApiLimits + tags_by_categories

[TexasCoding]

Summary

Two integration-test failures from #124, both caused by SDK models that matched the published OpenAPI spec but not the actual server response.

AccountApiLimits — server returns nested token buckets

Spec v3.13.0 declares read_limit/write_limit as ints. Live server returns:

{
  "usage_tier": "basic",
  "read":  {"bucket_capacity": 200, "refill_rate": 200},
  "write": {"bucket_capacity": 100, "refill_rate": 100}
}

• Added RateLimit model (bucket_capacity: int, refill_rate: int)
• AccountApiLimits.read_limit/.write_limit removed; replaced by .read/.write of type RateLimit
• Exported RateLimit from kalshi.__all__ and kalshi.models.__all__
• The old int fields never worked against the live server (the integration test was failing on day one), so practical migration impact is minimal — but flagged as breaking in CHANGELOG.md anyway

GetTagsForSeriesCategoriesResponse — server sends null lists

The Social category returns null instead of an empty list. Changed tags_by_categories: dict[str, list[str]] → dict[str, NullableList[str]]. The NullableList helper already exists in kalshi.types; this just propagates the null→[] collapse one level down into the dict values.

Verification

• Integration: tests/integration/test_account.py::TestAccount{Sync,Async}::test_limits ✅, tests/integration/test_search.py::TestSearch{Sync,Async}::test_tags_by_categories ✅
• Unit suite: 1608 passed
• uv run ruff check . clean
• uv run mypy kalshi/ clean (76 files, strict)
• Updated _contract_map.py to flag the spec-vs-server drift explicitly

Progress on #124

Closes 4 of 11 integration failures. Remaining:

• 1 — test_bad_auth_returns_auth_error (test uses now-public markets.list; needs auth-gated endpoint instead)
• 6 — test_order_groups × 3 + test_orders × 3 (all return not_found; demo limitation or setup issue — TBD)
• 1 — test_subaccounts.test_list_balances_reflects_ephemeral_subaccount (demo capped at 20 subaccounts; test doesn't clean up)

Each tracked as a separate follow-up PR.

Refs #124

Test plan

• Local integration run against demo: 4 previously-failing tests now pass
• Unit suite + ruff + mypy clean
• CI green

[claude]

Code Review — PR #126

Overall this is a solid, well-reasoned fix. The PR description is clear, the CHANGELOG migration guide is helpful, and the approach of following the live server over the published spec is pragmatic and correct. A few things worth addressing before merge.

---

Issues

1. Missing regression test for the null-in-dict-values bug (medium)

The motivating bug — tags_by_categories: {"Social": null} crashing at parse time — has no unit test in tests/test_search.py. The existing test_null_sport_ordering covers a top-level null, but not a null inside a dict value. Without a test, this can silently regress if someone later changes the type annotation.

Suggested addition to TestTagsByCategories:

def test_null_category_value_coerces_to_empty(self, search: SearchResource) -> None:
    with respx.mock:
        respx.get(...).mock(return_value=httpx.Response(
            200,
            json={"tags_by_categories": {"Sports": ["NFL"], "Social": None}},
        ))
        result = search.tags_by_categories()
        assert result.tags_by_categories["Social"] == []

2. Integration test assertion strength (minor)

The old integration assertions used >= 0; the new ones use > 0:

assert result.read.bucket_capacity > 0   # new — fails if any tier allows a 0 cap
assert result.read.refill_rate > 0

Unless the API guarantees positive values for all tiers (including suspended/restricted accounts), >= 0 is safer. The PR description shows the demo tier at 200/100 which is fine, but asserting strictness in an integration test that runs against a live server creates a fragile coupling. Recommend reverting to >= 0.

3. Verbose multi-line docstrings (minor, conventions)

CLAUDE.md specifies "never write multi-paragraph docstrings or multi-line comment blocks — one short line max." The new RateLimit docstring is 5 lines explaining token-bucket semantics. The AccountApiLimits docstring has a multi-line NOTE about spec drift. Both violate this. Trim each to a single sentence; the spec-drift context already lives in _contract_map.py and the CHANGELOG.

# RateLimit — before
class RateLimit(BaseModel):
    """Per-direction (read/write) token-bucket rate limit.

    The server enforces a token bucket per direction: ``bucket_capacity``
    tokens are allowed in a burst; ``refill_rate`` tokens are added per
    second up to the cap. Requests above the cap return 429.
    """
    
# RateLimit — after
class RateLimit(BaseModel):
    """Token-bucket rate limit for a single API direction (read or write)."""

4. No _contract_map.py drift note for GetTagsForSeriesCategoriesResponse (minor)

AccountApiLimits gets an explicit SPEC DRIFT note in _contract_map.py, but the search model's null-vs-empty-list drift doesn't. For consistency, the SportFilterDetails / ScopeList entries near line 225 could be joined by one for GetTagsForSeriesCategoriesResponse noting the same pattern. Not required, but it would make spec-drift grep results complete.

---

Strengths

• extra="allow" on RateLimit matches the defensive posture of the rest of the codebase.
• Reusing the existing NullableList type is exactly right — no new abstraction introduced.
• CHANGELOG breaking-change section with a before/after code example is excellent.
• Unit tests updated with realistic values (bucket_capacity vs. refill_rate relationship makes sense).
• _contract_map.py updated to document the spec deviation so the drift detector will catch any future spec fix.

---

Summary

The logic is correct and the approach is sound. The main asks are: (1) add a unit test for the null-in-dict-values case that motivated the search.py change, and (2) relax the integration assertions back to >= 0. The docstring and contract-map notes are minor style points.