feat: add rate limit tracking and public API

[banter240]

Essential improvements for production use:

Rate Limit Support (NEW):

• Add: Store response headers from API calls
• Add: Parse RateLimit headers per IETF draft spec
• Add: rate_limit property returning (limit, remaining) tuple
• Add: last_headers property for debugging
• Change: Use context manager to access headers before consuming body

Public API (NEW - enables extensions):

• Add: session property (get aiohttp ClientSession)
• Add: home_id property (get home ID)
• Add: access_token property (get OAuth token)
• Add: refresh_auth() public method (refresh token)

Model Fixes:

• Fix: ZoneState null nextTimeBlock handling (API sometimes returns null)

Breaking Changes: None (only additions and one critical bug fix)

All changes are backward compatible. Existing code works unchanged.

Enables Home Assistant integrations to:

• Track API quota usage (rate_limit property)
• Build extensions without private attribute access (public API)
• Handle edge cases in API responses (ZoneState fix)

[erwindouna]

Thanks for contributing, here an initial review. :)

[erwindouna]

Making solid progress. tadoasync is heavily tested. Would you mind including/updating tests, that way we can ensure we're releasing a solid package. :)

[erwindouna]

Not be too nitpicky, but we never exposed these before. I suppose this is from your other work? The refresh auth is something I might have doubts on, since the business logic should be that it checks per request if a refresh is needed.

[banter240]

Yeah, you're right, this is from my TadoHijack integration.
I need these for TadoX API support. The new Tado X hardware uses a completely separate API at hops.tado.com that's not covered by tadoasync's existing methods. I have to make direct HTTP requests to that API while reusing tadoasync's session and auth:

In TadoXApi class

await self._tado._refresh_auth()  # Refresh before our external request
headers = {"Authorization": f"Bearer {self._tado._access_token}"}
url = f"https://hops.tado.com/homes/{self._tado._home_id}/rooms"
async with self._tado._ensure_session().request(...) as response:
    return await response.json()

Since we're making requests to an external API (outside of tadoasync's _request() flow), we need manual access to the session, auth token, and refresh logic. Currently we're accessing _refresh_auth(), _access_token, _home_id, and _ensure_session() as private attributes, which is why we'd like to see them public.

The refresh_auth() method is needed because we're bypassing tadoasync's normal request flow entirely - we need to manually refresh before our own external API calls.

[erwindouna]

I see, that supports the hybrid solution, right?

[banter240]

Yes, exactly. Once we manage to integrate native Tado X support directly into tadoasync, we can refactor this and maybe make them private again. But for now, while I have to handle the Tado X API externally alongside tadoasync (the hybrid approach), it's much safer to have these exposed publicly rather than relying on private _ members.

[erwindouna]

Makes sense, I can accept that change.

[erwindouna]

So I think, the only thing left are updating the tests. :)