python-hilo 2026.10.1__tar.gz → 2026.10.2__tar.gz

{python_hilo-2026.10.1 → python_hilo-2026.10.2}/.devcontainer/devcontainer.json

@@ -47,7 +47,7 @@
     "ghcr.io/devcontainers/features/github-cli:1": {},
     "ghcr.io/jsburckhardt/devcontainer-features/uv:1": {}
   },
-  "image": "mcr.microsoft.com/devcontainers/python:3.11-bookworm",
+  "image": "mcr.microsoft.com/devcontainers/python:3-3.14-bookworm",
   "name": "A Python3, async interface to the Hilo API",
   "postCreateCommand": "uv sync --group dev --group test && uv run pre-commit install"
 }

{python_hilo-2026.10.1 → python_hilo-2026.10.2}/.github/workflows/tests.yaml

@@ -8,7 +8,7 @@ on:
   pull_request:
 
 env:
-  DEFAULT_PYTHON: 3.13
+  DEFAULT_PYTHON: "3.14"
 
 jobs:
   pre-commit:
@@ -19,12 +19,12 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Set up Python ${{ env.DEFAULT_PYTHON }}
-        uses: actions/setup-python@v7.0.0
+        uses: actions/setup-python@v7.1.0
         with:
           python-version: ${{ env.DEFAULT_PYTHON }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.2.0
+        uses: astral-sh/setup-uv@v10.3.1
 
       - name: Install dependencies
         run: uv sync --group dev
@@ -36,21 +36,25 @@ jobs:
 
   tests:
     runs-on: "ubuntu-latest"
-    name: Tests
+    name: Tests (${{ matrix.python-version }})
+    strategy:
+      matrix:
+        # Mirrors the Hilo integration, which still supports Home Assistant releases on 3.13.
+        python-version: ["3.13", "3.14"]
     steps:
       - name: Check out the repository
         uses: actions/checkout@v7
 
-      - name: Set up Python ${{ env.DEFAULT_PYTHON }}
-        uses: actions/setup-python@v7.0.0
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7.1.0
         with:
-          python-version: ${{ env.DEFAULT_PYTHON }}
+          python-version: ${{ matrix.python-version }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.2.0
+        uses: astral-sh/setup-uv@v10.3.1
 
       - name: Install dependencies
-        run: uv sync --group test
+        run: uv sync --python ${{ matrix.python-version }} --group test
 
       - name: Run tests
-        run: uv run pytest -v
+        run: uv run --python ${{ matrix.python-version }} pytest -v

{python_hilo-2026.10.1 → python_hilo-2026.10.2}/.pre-commit-config.yaml

@@ -14,10 +14,10 @@ repos:
     hooks:
       - id: ruff-format
         args: [--quiet]
-        files: ^pyhilo/.+\.py$
+        files: ^(pyhilo|tests)/.+\.py$
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
-        files: ^pyhilo/.+\.py$
+        files: ^(pyhilo|tests)/.+\.py$
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.1
     hooks:

python_hilo-2026.10.2/AGENTS.md

@@ -0,0 +1,56 @@
+# Coding Assistant Instructions: python-hilo Library
+
+This repository contains `pyhilo`, a standalone asynchronous Python client library for Hilo energy services (SignalR WebSocket, GraphQL, and REST APIs).
+
+## Git Commit Guidelines
+
+- **First line**: Short, specific imperative sentence (e.g. "Add abstract auth interface for token provider"). No emojis in titles.
+- **Commit description**: Focus on the **WHY** (problem, context, and architectural rationale). Keep it concise, factual, and proportional.
+- **Do NOT amend, squash, or rebase commits that have already been pushed to the PR branch after the PR is opened**: Reviewers need to follow the commit history and see what changed since their last review.
+
+## Development Commands
+
+- Install dependencies: `uv sync`
+- Run test suite: `uv run pytest`
+- Run a specific test: `uv run pytest tests/test_device.py`
+- Check linting and formatting: `uv run ruff check .` and `uv run ruff format --check .`
+
+## Architecture & Boundaries
+
+- **Strict Decoupling from Home Assistant**:
+  - This library MUST NEVER import `homeassistant` or depend on Home Assistant Core modules, constants, or types.
+  - The library must be 100% installable, testable, and runnable independently in any standard Python 3.13+ environment.
+- **Authentication Contract**:
+  - Expose an abstract base class `AbstractAuth` (`pyhilo.auth`):
+    ```python
+    class AbstractAuth(ABC):
+        @abstractmethod
+        async def async_get_access_token(self) -> str:
+            """Return a valid access token, refreshing if necessary."""
+    ```
+  - The library calls this method whenever it needs a valid token, leaving token storage and refresh mechanisms to the consumer (such as the Hilo Home Assistant integration or CLI tools).
+- **Backwards Compatibility**: When modifying public API signatures, provide temporary shims with deprecation warnings for at least 1–2 minor versions to prevent breaking downstream consumers.
+- **Credential Protection**: Never log raw access tokens, refresh tokens, passwords, or decoded JWT claims in `DEBUG` or `INFO` logs.
+
+## Testing Standards
+
+- Verify library protocol behavior, event decoding, device mapping, and error handling.
+- When writing tests or implementation code, ensure all parameters have precise type annotations. **The use of `Any` is strictly forbidden in new code.**
+- **Single purpose tests**: Each test function must verify only one specific behavior or outcome. Avoid testing multiple unrelated scenarios in a single test; split them into focused tests or use parametrization.
+- Prefer standard library `unittest.mock` (`AsyncMock`, `MagicMock`) over large bespoke stub classes.
+- Prefer `@pytest.mark.usefixtures` over unused fixture arguments.
+- Avoid branching (`if`/`else`) in tests; use `@pytest.mark.parametrize` with `pytest.param(..., id="...")` for table-driven testing.
+- Tests must execute cleanly with `uv run pytest` without requiring network access.
+
+## Good practices
+
+- Built with `asyncio`, `aiohttp`, `pysignalr`, and `gql`.
+- Non-blocking I/O: avoid any synchronous disk reads/writes on active event loops. Accept explicit file paths when managing state.
+- Keep `try` clauses as small as possible.
+- When validation guarantees a dict key exists, prefer direct key access (`data["key"]`) instead of `.get("key")`.
+- Keep comments concise and explain only the WHY. Do not restate code or use divider comments (`# --- XYZ ---`).
+- CalVer format: Versions follow `vYYYY.MM.MICRO` (e.g. `v2026.10.1`).
+
+## AI policy
+
+Autonomous contributions are not accepted. Every change must be reviewed and understood by a human contributor before submission. Never open pull requests, create release tags, or post comments autonomously without explicit contributor instruction.

{python_hilo-2026.10.1 → python_hilo-2026.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-hilo
-Version: 2026.10.1
+Version: 2026.10.2
 Summary: A Python3, async interface to the Hilo API
 Project-URL: Repository, https://github.com/dvd-dev/python-hilo
 Author-email: David Vallee Delisle <me@dvd.dev>
@@ -11,11 +11,12 @@ Classifier: Framework :: aiohttp
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Home Automation
-Requires-Python: >=3.11
+Requires-Python: >=3.13
 Requires-Dist: aiofiles>=23.2.1
 Requires-Dist: aiohttp>=3.8.0
 Requires-Dist: backoff>=1.11.1
@@ -34,7 +35,7 @@ Description-Content-Type: text/markdown
 [![Build Status][build-shield]][build]
 [![Open in Dev Containers][devcontainer-shield]][devcontainer]
 
-`python-hilo` (aka `pyhilo`) is a Python 3.11, `asyncio`-driven interface to the unofficial
+`python-hilo` (aka `pyhilo`) is a Python 3.13+, `asyncio`-driven interface to the unofficial
 Hilo API from Hydro Quebec. This is meant to be integrated into Home Assistant but can also
 be used as a standalone library.
 
@@ -63,7 +64,7 @@ for formatting and linting.
 
 You need at least:
 
-- Python 3.11+
+- Python 3.13+
 - [uv][uv]
 
 To install all packages, including all development requirements:

{python_hilo-2026.10.1 → python_hilo-2026.10.2}/README.md

@@ -6,7 +6,7 @@
 [![Build Status][build-shield]][build]
 [![Open in Dev Containers][devcontainer-shield]][devcontainer]
 
-`python-hilo` (aka `pyhilo`) is a Python 3.11, `asyncio`-driven interface to the unofficial
+`python-hilo` (aka `pyhilo`) is a Python 3.13+, `asyncio`-driven interface to the unofficial
 Hilo API from Hydro Quebec. This is meant to be integrated into Home Assistant but can also
 be used as a standalone library.
 
@@ -35,7 +35,7 @@ for formatting and linting.
 
 You need at least:
 
-- Python 3.11+
+- Python 3.13+
 - [uv][uv]
 
 To install all packages, including all development requirements:

python_hilo-2026.10.2/doc/README.md

@@ -0,0 +1,92 @@
+# Hilo API reference payloads
+
+Captured responses from Hilo's services, grouped by transport to mirror the library modules.
+IDs, URNs and serial numbers in the payload files are anonymized.
+
+| Folder | Transport | Library module | Contents |
+|---|---|---|---|
+| [`rest/`](rest/) | HTTPS REST | `pyhilo/api.py` | Automation (`/Locations`, `/Weather`) and challenge season endpoints |
+| [`graphql/`](graphql/) | GraphQL subscription | `pyhilo/graphql.py` | `onAnyDeviceUpdated` payloads per device type |
+| [`signalr/devicehub/`](signalr/devicehub/) | SignalR WebSocket | `pyhilo/signalr.py` | DeviceHub messages |
+| [`signalr/challengehub/`](signalr/challengehub/) | SignalR WebSocket | `pyhilo/signalr.py` | ChallengeHub messages, 2025-26 season onward (CH = Winter Credits, Flex = Flex D) |
+| [`signalr/challengehub/legacy-pre-2025/`](signalr/challengehub/legacy-pre-2025/) | SignalR WebSocket | — | Challenge messages before the CH/Flex split; kept for reference |
+| [`postman/`](postman/) | — | — | Postman collection and environment for manual testing |
+
+## Adding a payload
+
+1. Strip tokens, location URNs, serial numbers and personal data before committing.
+2. Name REST files after the endpoint (`season_events_ch_2025.json`) and SignalR/GraphQL files after the message target (`EventCHDetailsInitialValuesReceived.json`).
+3. Add a short suffix for variants (`-during-event`, `-empty`, `-meter`).
+
+# Using Postman to query Hilo
+
+Import [`postman/hilo.postman_collection.json`](postman/hilo.postman_collection.json) and [`postman/hilo-prod.postman_environment.json`](postman/hilo-prod.postman_environment.json), then select the **Hilo Prod** environment.
+
+## Authentication
+
+The collection uses OAuth 2.0 at the collection level. Open the collection's **Authorization** tab, click **Get New Access Token**, log in with your Hilo credentials in the browser window, then click **Use Token**. Every request in the collection inherits that token.
+
+Tokens are short-lived and contain personally identifiable information. Do not share them or commit an exported environment that contains them.
+
+## REST requests
+
+With the access token set, the REST requests (`1-Get Locations`, `Get SeasonsSummary`, `Get CHEvents`, `Get FlexEvents`, ...) can be sent directly.
+
+## Connecting to a hub
+
+Each hub folder (`DeviceHub`, `ChallengeHub`) contains two negotiate requests. Send them in order:
+
+1. `1-API Hilo ... Hub Negotiate` stores the hub URL and hub access token in the environment (`_deviceHubUrl` / `_deviceHubAccessToken`, or `_challengeHubUrl` / `_challengeHubAccessToken`).
+2. `2-... Hub Negotiate` stores the connection token (`_deviceHubConnectionToken` or `_challengeHubConnectionToken`).
+
+Then open a new WebSocket request in Postman:
+
+1. Use the hub URL from the environment (`{{_deviceHubUrl}}` or `{{_challengeHubUrl}}`).
+2. In **Headers**, add `Authorization` with the value `Bearer {{_deviceHubAccessToken}}` (or `Bearer {{_challengeHubAccessToken}}`).
+3. Connect, then send the handshake below. The trailing record separator character `chr(30)` is required after every message.
+
+```
+{
+    "protocol": "json",
+    "version": 1
+}
+```
+
+### DeviceHub
+
+Invoke `SubscribeToLocation` with your location ID to get your device information:
+
+```
+{
+    "arguments": [
+        69420
+    ],
+    "invocationId": "0",
+    "target": "SubscribeToLocation",
+    "type": 1
+}
+```
+
+You should receive a [`DeviceListInitialValuesReceived`](signalr/devicehub/DeviceListInitialValuesReceived.json) message back.
+
+### ChallengeHub
+
+Since the 2025-2026 season and the addition of Flex D, messages are split between Winter Credits (Crédit Hivernal) and Flex D. Winter Credits targets contain `CH` and Flex D targets contain `Flex`. Each rate has its own event ID; for example, event 337 was for Winter Credits and event 338 for Flex D, both at the same time. You only have access to the one matching your rate.
+
+#### SubscribeToEventCH or SubscribeToEventFlex
+
+```
+{
+    "arguments": [
+        {
+            "locationHiloId": "urn:YOUR-URN",
+            "eventId": ID(numeric)
+        }
+    ],
+    "invocationId": "1",
+    "target": "SubscribeToEventCH",
+    "type": 1
+}
+```
+
+Returns [`EventCHDetailsInitialValuesReceived`](signalr/challengehub/EventCHDetailsInitialValuesReceived.json) or [`EventFlexDetailsInitialValuesReceived`](signalr/challengehub/EventFlexDetailsInitialValuesReceived.json).

python_hilo-2026.10.2/doc/graphql/onAnyDeviceUpdated-cee.json

@@ -0,0 +1,33 @@
+{
+  "data": {
+    "onAnyDeviceUpdated": {
+      "deviceType": "cee",
+      "locationHiloId": "urn:hilo:crm:00000-abcdef:0",
+      "transmissionTime": "2026-10-24T19:46:35.207Z",
+      "operationId": "00000000-0000-0000-0000-000000000002",
+      "status": "REPORT",
+      "device": {
+        "deviceType": "cee",
+        "hiloId": "urn:hilo:philo:4a5b6c7d8e9f0001:0",
+        "physicalAddress": "4A5B6C7D8E9F0001",
+        "connectionStatus": "CONNECTED",
+        "gDState": "EXCLUDED",
+        "version": "45",
+        "probeTemp": {
+          "value": 54,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "zigbeeVersion": "45",
+        "state": "ON",
+        "ccrType": "WATER_HEATER",
+        "alerts": [
+          "0"
+        ],
+        "power": {
+          "value": 0,
+          "kind": "WATT"
+        }
+      }
+    }
+  }
+}

python_hilo-2026.10.2/doc/graphql/onAnyDeviceUpdated-meter.json

@@ -0,0 +1,22 @@
+{
+  "data": {
+    "onAnyDeviceUpdated": {
+      "deviceType": "meter",
+      "locationHiloId": "urn:hilo:crm:00000-abcdef:0",
+      "transmissionTime": "2026-10-24T19:48:54.966Z",
+      "operationId": "00000000-0000-0000-0000-000000000001",
+      "status": "REPORT",
+      "device": {
+        "deviceType": "meter",
+        "hiloId": "urn:hilo:philo:0x006baa0000000001-smart_meter:0",
+        "physicalAddress": "0x006BAA0000000001-smart_meter",
+        "connectionStatus": "CONNECTED",
+        "zigBeeChannel": 24,
+        "power": {
+          "value": 0.572,
+          "kind": "KILOWATT"
+        }
+      }
+    }
+  }
+}

python_hilo-2026.10.2/doc/rest/location_weather.json

@@ -0,0 +1,7 @@
+{
+  "temperature": 10.0,
+  "time": "0001-01-01T00:00:00Z",
+  "condition": "Clear",
+  "icon": 0,
+  "humidity": 72.0
+}

python_hilo-2026.10.2/doc/rest/season_events_ch_2025.json

@@ -0,0 +1,42 @@
+{
+  "season": 2025,
+  "events": [
+    {
+      "id": 378,
+      "startDateUtc": "2026-03-18T08:00:00+00:00",
+      "period": "AM",
+      "reward": 11.68,
+      "energySavingsWh": 20570,
+      "status": "Success",
+      "isPreseasonEvent": false,
+      "isCredited": true,
+      "isFlatRate": false,
+      "isInsufficientReduction": false
+    },
+    {
+      "id": 377,
+      "startDateUtc": "2026-03-03T09:00:00+00:00",
+      "period": "AM",
+      "reward": 17.95,
+      "energySavingsWh": 31620,
+      "status": "Success",
+      "isPreseasonEvent": false,
+      "isCredited": true,
+      "isFlatRate": false,
+      "isInsufficientReduction": false
+    },
+    {
+      "id": 373,
+      "startDateUtc": "2026-02-08T09:00:00+00:00",
+      "period": "AM",
+      "reward": 20.56,
+      "energySavingsWh": 36220,
+      "status": "Success",
+      "isPreseasonEvent": false,
+      "isCredited": true,
+      "isFlatRate": false,
+      "isInsufficientReduction": false
+    }
+  ],
+  "periodId": "Q0h8dXJuOmhpbG86Y3JtOjAwMDAwLWFiY2RlZjowfDIwMjUtMTEtMDFUMTM6MDE6MTcuODA4Nzc4NVo="
+}

python_hilo-2026.10.2/doc/rest/season_events_ch_2026_empty.json

@@ -0,0 +1,5 @@
+{
+  "season": 2026,
+  "events": [],
+  "periodId": "Q0h8dXJuOmhpbG86Y3JtOjAwMDAwLWFiY2RlZjowfDIwMjUtMTEtMDFUMTM6MDE6MTcuODA4Nzc4NVo="
+}

python_hilo-2026.10.2/doc/rest/season_events_hilo_2024.json

@@ -0,0 +1,36 @@
+{
+  "season": 2024,
+  "events": [
+    {
+      "id": 303,
+      "startDateUtc": "2025-03-03T09:00:00+00:00",
+      "period": "AM",
+      "reportId": 1000000,
+      "reward": 20.39,
+      "energySavingsWh": 37081.6845703125,
+      "status": "Success",
+      "isPreseasonEvent": false
+    },
+    {
+      "id": 302,
+      "startDateUtc": "2025-02-19T09:00:00+00:00",
+      "period": "AM",
+      "reportId": 1000001,
+      "reward": 21.85,
+      "energySavingsWh": 39730.3349609375,
+      "status": "Success",
+      "isPreseasonEvent": false
+    },
+    {
+      "id": 301,
+      "startDateUtc": "2025-02-18T09:00:00+00:00",
+      "period": "AM",
+      "reportId": 1000002,
+      "reward": 23.91,
+      "energySavingsWh": 43477.09521484375,
+      "status": "Success",
+      "isPreseasonEvent": false
+    }
+  ],
+  "periodId": "SGlsb3x1cm46aGlsbzpjcm06MDAwMDAtYWJjZGVmOjB8MjAyMi0wNi0yMlQxOTo1MDozOC4wMDAwMDAwWg=="
+}

python_hilo-2026.10.2/doc/rest/seasons_summary.json

@@ -0,0 +1,27 @@
+[
+  {
+    "season": 2026,
+    "ratePlan": "CH",
+    "periodId": "Q0h8dXJuOmhpbG86Y3JtOjAwMDAwLWFiY2RlZjowfDIwMjUtMTEtMDFUMTM6MDE6MTcuODA4Nzc4NVo="
+  },
+  {
+    "season": 2025,
+    "ratePlan": "CH",
+    "periodId": "Q0h8dXJuOmhpbG86Y3JtOjAwMDAwLWFiY2RlZjowfDIwMjUtMTEtMDFUMTM6MDE6MTcuODA4Nzc4NVo="
+  },
+  {
+    "season": 2024,
+    "ratePlan": "Hilo",
+    "periodId": "SGlsb3x1cm46aGlsbzpjcm06MDAwMDAtYWJjZGVmOjB8MjAyMi0wNi0yMlQxOTo1MDozOC4wMDAwMDAwWg=="
+  },
+  {
+    "season": 2023,
+    "ratePlan": "Hilo",
+    "periodId": "SGlsb3x1cm46aGlsbzpjcm06MDAwMDAtYWJjZGVmOjB8MjAyMi0wNi0yMlQxOTo1MDozOC4wMDAwMDAwWg=="
+  },
+  {
+    "season": 2022,
+    "ratePlan": "Hilo",
+    "periodId": "SGlsb3x1cm46aGlsbzpjcm06MDAwMDAtYWJjZGVmOjB8MjAyMi0wNi0yMlQxOTo1MDozOC4wMDAwMDAwWg=="
+  }
+]

{python_hilo-2026.10.1 → python_hilo-2026.10.2}/pyhilo/__init__.py

@@ -1,6 +1,7 @@
 """Define the hilo package."""
 
 from pyhilo.api import API
+from pyhilo.auth import AbstractAuth
 from pyhilo.const import UNMONITORED_DEVICES
 from pyhilo.device import HiloDevice
 from pyhilo.device.switch import Switch
@@ -12,6 +13,7 @@ from pyhilo.util import from_utc_timestamp, time_diff
 
 __all__ = [
     "API",
+    "AbstractAuth",
     "Devices",
     "HiloDevice",
     "Event",

{python_hilo-2026.10.1 → python_hilo-2026.10.2}/pyhilo/api.py

@@ -13,8 +13,8 @@ from urllib import parse
 from aiohttp import ClientSession
 from aiohttp.client_exceptions import ClientResponseError
 import backoff
-from homeassistant.helpers.config_entry_oauth2_flow import OAuth2Session
 
+from pyhilo.auth import AbstractAuth, _LegacyOAuthSessionAuth
 from pyhilo.const import (
     ANDROID_CLIENT_ENDPOINT,
     ANDROID_CLIENT_HEADERS,
@@ -62,7 +62,8 @@ class API:
         self,
         *,
         session: ClientSession,
-        oauth_session: OAuth2Session,
+        auth: AbstractAuth | None = None,
+        oauth_session: Any = None,
         request_retries: int = REQUEST_RETRY,
         log_traces: bool = False,
         state_yaml: str = DEFAULT_STATE_FILE,
@@ -75,7 +76,8 @@ class API:
         self.async_request = self._wrap_request_method(self._request_retries)
         self.device_attributes = get_device_attributes()
         self.session: ClientSession = session
-        self._oauth_session = oauth_session
+        self._auth = self._resolve_auth(auth, oauth_session)
+        self._access_token: str | None = None
         self.signalr_devices: SignalRHub
         self.signalr_challenges: SignalRHub
         self.log_traces = log_traces
@@ -85,12 +87,24 @@ class API:
         self._device_cache: list[dict[str, Any]] = []
         self._device_cache_event: asyncio.Event = asyncio.Event()
 
+    @staticmethod
+    def _resolve_auth(auth: AbstractAuth | None, oauth_session: Any) -> AbstractAuth:
+        """Pick the auth provider, adapting the deprecated ``oauth_session``."""
+        if auth is not None and oauth_session is not None:
+            raise ValueError("Pass either auth or oauth_session, not both")
+        if auth is not None:
+            return auth
+        if oauth_session is not None:
+            return _LegacyOAuthSessionAuth(oauth_session)
+        raise ValueError("An auth provider is required")
+
     @classmethod
     async def async_create(
         cls,
         *,
         session: ClientSession,
-        oauth_session: OAuth2Session,
+        auth: AbstractAuth | None = None,
+        oauth_session: Any = None,
         request_retries: int = REQUEST_RETRY,
         log_traces: bool = False,
         state_yaml: str = DEFAULT_STATE_FILE,
@@ -98,8 +112,10 @@ class API:
         """Get an authenticated API object.
         :param session: The ``aiohttp`` ``ClientSession`` session used for all HTTP requests
         :type session: ``aiohttp.client.ClientSession``
-        :param oauth_session: The session to make requests authenticated with OAuth2.
-        :type oauth_session: ``config_entry_oauth2_flow.OAuth2Session``
+        :param auth: Provides valid access tokens for API requests.
+        :type auth: :class:`pyhilo.auth.AbstractAuth`
+        :param oauth_session: Deprecated, use ``auth`` instead. A Home Assistant
+            ``OAuth2Session``, adapted internally.
         :param request_retries: The default number of request retries to use
         :type request_retries: ``int``
         :param state_yaml: Path of the file where the API state (tokens, etc.) is saved.
@@ -107,6 +123,7 @@ class API:
         """
         api = cls(
             session=session,
+            auth=auth,
             oauth_session=oauth_session,
             request_retries=request_retries,
             log_traces=log_traces,
@@ -132,16 +149,12 @@ class API:
 
     async def async_get_access_token(self) -> str:
         """Return a valid access token."""
-        if not self._oauth_session.valid_token:
-            await self._oauth_session.async_ensure_token_valid()
-
-        access_token = str(self._oauth_session.token["access_token"])
-        LOG.debug("SignalR access token is %s", access_token)
+        self._access_token = await self._auth.async_get_access_token()
 
         urn = self.urn
         LOG.debug("Extracted URN: %s", urn)
 
-        return str(self._oauth_session.token["access_token"])
+        return self._access_token
 
     @property
     def urn(self) -> str | None:
@@ -150,10 +163,9 @@ class API:
             return self._urn
 
         try:
-            if not self._oauth_session.valid_token:
+            if not self._access_token:
                 return None
-            token = self._oauth_session.token["access_token"]
-            payload_part = token.split(".")[1]
+            payload_part = self._access_token.split(".")[1]
             # Add padding if necessary
             padding = 4 - len(payload_part) % 4
             if padding != 4:

python_hilo-2026.10.2/pyhilo/auth.py

@@ -0,0 +1,42 @@
+"""Authentication interface for the Hilo API."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pyhilo.const import LOG
+
+
+class AbstractAuth(ABC):
+    """Supplies valid Hilo access tokens to :class:`pyhilo.api.API`.
+
+    Applications subclass this and implement :meth:`async_get_access_token`.
+    In Home Assistant, the integration wraps its ``OAuth2Session``; standalone
+    scripts can return a static token or run their own refresh logic.
+    """
+
+    @abstractmethod
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token, refreshing it if needed."""
+
+
+class _LegacyOAuthSessionAuth(AbstractAuth):
+    """Adapts a Home Assistant ``OAuth2Session`` passed as ``oauth_session``.
+
+    Deprecated: kept so integration releases that still pass ``oauth_session``
+    keep working. The session is duck-typed so pyhilo never imports
+    Home Assistant.
+    """
+
+    def __init__(self, oauth_session: Any) -> None:
+        LOG.warning(
+            "Passing oauth_session to pyhilo.API is deprecated and will be "
+            "removed in a future release; pass an AbstractAuth via auth instead"
+        )
+        self._oauth_session = oauth_session
+
+    async def async_get_access_token(self) -> str:
+        if not self._oauth_session.valid_token:
+            await self._oauth_session.async_ensure_token_valid()
+        return str(self._oauth_session.token["access_token"])

{python_hilo-2026.10.1 → python_hilo-2026.10.2}/pyhilo/const.py

@@ -11,7 +11,7 @@ INSTANCE_ID: Final = str(uuid.uuid4())[24:]
 LOG: Final = logging.getLogger(__package__)
 DEFAULT_STATE_FILE: Final = "hilo_state.yaml"
 REQUEST_RETRY: Final = 9
-PYHILO_VERSION: Final = "2026.10.01"
+PYHILO_VERSION: Final = "2026.10.02"
 # TODO: Find a way to keep previous line in sync with pyproject.toml automatically
 
 CONTENT_TYPE_FORM: Final = "application/x-www-form-urlencoded"

{python_hilo-2026.10.1 → python_hilo-2026.10.2}/pyhilo/device/graphql_value_mapper.py

@@ -76,7 +76,7 @@ class GraphqlValueMapper:
 
     def _build_smart_meter(self, device: Dict[str, Any]) -> list[Dict[str, Any]]:
         attributes = []
-        if device.get("zigbeeChannel") is not None:
+        if device.get("zigBeeChannel") is not None:
             attributes.append(
                 self.build_attribute(
                     device["hiloId"], "ZigbeeChannel", device["zigBeeChannel"]