Support camel case and pascal case simultaneously (#244)

* Support camel case and pascal case simultaneously

* Rename init tests to legacy

* Rename new tests to replace

* Adjust comment

* Flake8

* Fix mypy

* Detect version automatically

Author: puddly

python_otbr_api/__init__.py

@@ -1,8 +1,12 @@
 """API to interact with the Open Thread Border Router REST API."""
 
 from __future__ import annotations
+
+from enum import Enum
 from http import HTTPStatus
+from typing import Any
 import json
+import logging
 
 import aiohttp
 import voluptuous as vol  # type: ignore[import]
@@ -13,6 +17,60 @@
 # https://github.com/openthread/openthread/discussions/8567#discussioncomment-4468920
 PENDING_DATASET_DELAY_TIMER = 5 * 60 * 1000
 
+_LOGGER = logging.getLogger(__name__)
+
+# OTBR flipped the REST API from PascalCase to camelCase in ot-br-posix
+# PR #2514 (Sept 2025). The models speak camelCase internally; this table
+# translates both directions at the HTTP boundary for legacy servers.
+_CAMEL_TO_PASCAL: dict[str, str] = {
+    # Timestamp
+    "authoritative": "Authoritative",
+    "seconds": "Seconds",
+    "ticks": "Ticks",
+    # SecurityPolicy
+    "autonomousEnrollment": "AutonomousEnrollment",
+    "commercialCommissioning": "CommercialCommissioning",
+    "externalCommissioning": "ExternalCommissioning",
+    "nativeCommissioning": "NativeCommissioning",
+    "networkKeyProvisioning": "NetworkKeyProvisioning",
+    "nonCcmRouters": "NonCcmRouters",
+    "obtainNetworkKey": "ObtainNetworkKey",
+    "rotationTime": "RotationTime",
+    "routers": "Routers",
+    "tobleLink": "TobleLink",
+    # ActiveDataSet
+    "activeTimestamp": "ActiveTimestamp",
+    "channelMask": "ChannelMask",
+    "channel": "Channel",
+    "extPanId": "ExtPanId",
+    "meshLocalPrefix": "MeshLocalPrefix",
+    "networkKey": "NetworkKey",
+    "networkName": "NetworkName",
+    "panId": "PanId",
+    "pskc": "PSKc",
+    "securityPolicy": "SecurityPolicy",
+    # PendingDataSet
+    "activeDataset": "ActiveDataset",
+    "delay": "Delay",
+    "pendingTimestamp": "PendingTimestamp",
+}
+_PASCAL_TO_CAMEL: dict[str, str] = {v: k for k, v in _CAMEL_TO_PASCAL.items()}
+
+
+class KeyFormat(Enum):
+    """JSON key format used by the OTBR REST API.
+
+    PASCAL_CASE is the pre-Sept-2025 wire format (ot-br-posix pre-#2514):
+    writes are rewritten to PascalCase. CAMEL_CASE covers every post-flip
+    server, including the Sept-2025..April-2026 window where some keys
+    (e.g. `Routers` in SecurityPolicy) still came back PascalCase — reads
+    always run through the PascalCase normalization table so those
+    stragglers are picked up transparently.
+    """
+
+    CAMEL_CASE = "camel"
+    PASCAL_CASE = "pascal"
+
 
 class OTBRError(Exception):
     """Raised on error."""
@@ -30,20 +88,69 @@ class ThreadNetworkActiveError(OTBRError):
     """Raised on attempts to modify the active dataset when thread network is active."""
 
 
+def _rewrite_keys(data: Any, mapping: dict[str, str]) -> Any:
+    """Recursively rename dict keys according to mapping; pass through others."""
+    if not isinstance(data, dict):
+        return data
+    return {mapping.get(k, k): _rewrite_keys(v, mapping) for k, v in data.items()}
+
+
 class OTBR:  # pylint: disable=too-few-public-methods
     """Class to interact with the Open Thread Border Router REST API."""
 
     def __init__(
-        self, url: str, session: aiohttp.ClientSession, timeout: int = 10
+        self,
+        url: str,
+        session: aiohttp.ClientSession,
+        timeout: int = 10,
+        *,
+        key_format: KeyFormat | None = None,
     ) -> None:
         """Initialize."""
         self._session = session
         self._url = url
         self._timeout = timeout
+        self._key_format = key_format
+
+    async def _maybe_detect_key_format(self) -> None:
+        """Probe the OTBR REST API to determine the JSON key format."""
+        if self._key_format is not None:
+            return
+
+        response = await self._session.get(
+            f"{self._url}/api/actions",
+            timeout=aiohttp.ClientTimeout(total=self._timeout),
+        )
+
+        if response.status == HTTPStatus.OK:
+            self._key_format = KeyFormat.CAMEL_CASE
+        elif response.status == HTTPStatus.NOT_FOUND:
+            self._key_format = KeyFormat.PASCAL_CASE
+        else:
+            raise OTBRError(
+                f"could not detect OTBR version: unexpected http status "
+                f"{response.status}"
+            )
+
+        _LOGGER.debug("Detected OTBR JSON key format: %s", self._key_format)
+
+    def _encode(self, data: dict) -> dict:
+        """Rewrite a camelCase body to the detected wire format."""
+        if self._key_format == KeyFormat.PASCAL_CASE:
+            return _rewrite_keys(data, _CAMEL_TO_PASCAL)
+        return data
+
+    def _decode(self, data: dict) -> dict:
+        """Normalize a wire response body to camelCase."""
+
+        # Runs unconditionally: camelCase keys aren't in the table so they pass through
+        # untouched, while any PascalCase stragglers (full legacy or transition-era
+        # leftovers like `Routers`) get fixed.
+        return _rewrite_keys(data, _PASCAL_TO_CAMEL)
 
     async def factory_reset(self) -> None:
         """Factory reset the router."""
-
+        await self._maybe_detect_key_format()
         response = await self._session.delete(
             f"{self._url}/node",
             timeout=aiohttp.ClientTimeout(total=10),
@@ -57,6 +164,7 @@ async def factory_reset(self) -> None:
 
     async def get_border_agent_id(self) -> bytes:
         """Get the border agent ID."""
+        await self._maybe_detect_key_format()
         response = await self._session.get(
             f"{self._url}/node/ba-id",
             timeout=aiohttp.ClientTimeout(total=self._timeout),
@@ -75,7 +183,7 @@ async def get_border_agent_id(self) -> bytes:
 
     async def set_enabled(self, enabled: bool) -> None:
         """Enable or disable the router."""
-
+        await self._maybe_detect_key_format()
         response = await self._session.put(
             f"{self._url}/node/state",
             json="enable" if enabled else "disable",
@@ -91,6 +199,7 @@ async def get_active_dataset(self) -> ActiveDataSet | None:
         Returns None if there is no active operational dataset.
         Raises if the http status is 400 or higher or if the response is invalid.
         """
+        await self._maybe_detect_key_format()
         response = await self._session.get(
             f"{self._url}/node/dataset/active",
             timeout=aiohttp.ClientTimeout(total=self._timeout),
@@ -103,7 +212,7 @@ async def get_active_dataset(self) -> ActiveDataSet | None:
             raise OTBRError(f"unexpected http status {response.status}")
 
         try:
-            return ActiveDataSet.from_json(await response.json())
+            return ActiveDataSet.from_json(self._decode(await response.json()))
         except (json.JSONDecodeError, vol.Error) as exc:
             raise OTBRError("unexpected API response") from exc
 
@@ -113,6 +222,7 @@ async def get_active_dataset_tlvs(self) -> bytes | None:
         Returns None if there is no active operational dataset.
         Raises if the http status is 400 or higher or if the response is invalid.
         """
+        await self._maybe_detect_key_format()
         response = await self._session.get(
             f"{self._url}/node/dataset/active",
             headers={"Accept": "text/plain"},
@@ -136,6 +246,7 @@ async def get_pending_dataset_tlvs(self) -> bytes | None:
         Returns None if there is no pending operational dataset.
         Raises if the http status is 400 or higher or if the response is invalid.
         """
+        await self._maybe_detect_key_format()
         response = await self._session.get(
             f"{self._url}/node/dataset/pending",
             headers={"Accept": "text/plain"},
@@ -160,9 +271,10 @@ async def create_active_dataset(self, dataset: ActiveDataSet) -> None:
         not set will be automatically set by the open thread border router.
         Raises if the http status is 400 or higher or if the response is invalid.
         """
+        await self._maybe_detect_key_format()
         response = await self._session.put(
             f"{self._url}/node/dataset/active",
-            json=dataset.as_json(),
+            json=self._encode(dataset.as_json()),
             timeout=aiohttp.ClientTimeout(total=self._timeout),
         )
 
@@ -173,6 +285,7 @@ async def create_active_dataset(self, dataset: ActiveDataSet) -> None:
 
     async def delete_active_dataset(self) -> None:
         """Delete active operational dataset."""
+        await self._maybe_detect_key_format()
         response = await self._session.delete(
             f"{self._url}/node/dataset/active",
             timeout=aiohttp.ClientTimeout(total=self._timeout),
@@ -190,9 +303,10 @@ async def create_pending_dataset(self, dataset: PendingDataSet) -> None:
         not set will be automatically set by the open thread border router.
         Raises if the http status is 400 or higher or if the response is invalid.
         """
+        await self._maybe_detect_key_format()
         response = await self._session.put(
             f"{self._url}/node/dataset/pending",
-            json=dataset.as_json(),
+            json=self._encode(dataset.as_json()),
             timeout=aiohttp.ClientTimeout(total=self._timeout),
         )
 
@@ -203,6 +317,7 @@ async def create_pending_dataset(self, dataset: PendingDataSet) -> None:
 
     async def delete_pending_dataset(self) -> None:
         """Delete pending operational dataset."""
+        await self._maybe_detect_key_format()
         response = await self._session.delete(
             f"{self._url}/node/dataset/pending",
             timeout=aiohttp.ClientTimeout(total=self._timeout),
@@ -218,7 +333,7 @@ async def set_active_dataset_tlvs(self, dataset: bytes) -> None:
 
         Raises if the http status is 400 or higher or if the response is invalid.
         """
-
+        await self._maybe_detect_key_format()
         response = await self._session.put(
             f"{self._url}/node/dataset/active",
             data=dataset.hex(),
@@ -258,6 +373,7 @@ async def get_extended_address(self) -> bytes:
 
         Raises if the http status is not 200 or if the response is invalid.
         """
+        await self._maybe_detect_key_format()
         response = await self._session.get(
             f"{self._url}/node/ext-address",
             headers={"Accept": "application/json"},
@@ -277,7 +393,7 @@ async def get_coprocessor_version(self) -> str:
 
         Raises if the http status is not 200 or if the response is invalid.
         """
-
+        await self._maybe_detect_key_format()
         response = await self._session.get(
             f"{self._url}/node/coprocessor/version",
             headers={"Accept": "application/json"},