Enhance OverkizClient and models to support payload serialization with camelCase conversion and omission of None fields

Author: iMicknl

pyoverkiz/client.py

@@ -86,6 +86,7 @@
     State,
 )
 from pyoverkiz.obfuscate import obfuscate_sensitive_data
+from pyoverkiz.serializers import prepare_payload
 from pyoverkiz.types import JSON
 
 
@@ -659,10 +660,13 @@ async def execute_action_group(
         """
 
         """Send several commands in one call"""
-        payload = {
-            "label": label,
-            "actions": actions,
-        }
+
+        # Build a logical (snake_case) payload using model helpers and convert it
+        # to the exact JSON schema expected by the API (camelCase + small fixes).
+        payload = {"label": label, "actions": [a.to_payload() for a in actions]}
+
+        # Prepare final payload with camelCase keys and special abbreviation handling
+        final_payload = prepare_payload(payload)
 
         if mode == CommandMode.GEOLOCATED:
             url = "exec/apply/geolocated"
@@ -673,7 +677,7 @@ async def execute_action_group(
         else:
             url = "exec/apply"
 
-        response: dict = await self.__post(url, payload)
+        response: dict = await self.__post(url, final_payload)
 
         return cast(str, response["execId"])
 

pyoverkiz/models.py

@@ -438,6 +438,25 @@ def __init__(
         self.parameters = parameters
         self.type = type
 
+    def to_payload(self) -> dict[str, object]:
+        """Return a JSON-serializable payload for this command.
+
+        The payload uses snake_case keys; the client will convert to camelCase
+        and apply small key fixes (like `deviceURL`) before sending.
+        """
+        payload: dict[str, object] = {"name": str(self.name)}
+
+        if self.type is not None:
+            payload["type"] = self.type
+
+        if self.parameters is not None:
+            payload["parameters"] = [
+                p if isinstance(p, (str, int, float, bool)) else str(p)
+                for p in self.parameters  # type: ignore[arg-type]
+            ]
+
+        return payload
+
 
 @define(init=False, kw_only=True)
 class Event:
@@ -555,9 +574,21 @@ class Action:
     device_url: str
     commands: list[Command]
 
-    def __init__(self, device_url: str, commands: list[dict[str, Any]]):
+    def __init__(self, device_url: str, commands: list[dict[str, Any] | Command]):
         self.device_url = device_url
-        self.commands = [Command(**c) for c in commands] if commands else []
+        self.commands = [
+            c if isinstance(c, Command) else Command(**c) for c in commands
+        ]
+
+    def to_payload(self) -> dict[str, object]:
+        """Return a JSON-serializable payload for this action (snake_case).
+
+        The final camelCase conversion is handled by the client.
+        """
+        return {
+            "device_url": self.device_url,
+            "commands": [c.to_payload() for c in self.commands],
+        }
 
 
 @define(init=False, kw_only=True)

pyoverkiz/serializers.py

@@ -0,0 +1,39 @@
+"""Helpers for preparing API payloads.
+
+This module centralizes JSON key formatting and any small transport-specific
+fixes (like mapping "deviceUrl" -> "deviceURL"). Models should produce
+logical snake_case payloads and the client should call `prepare_payload`
+before sending the payload to Overkiz.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import humps
+
+# Small mapping for keys that need special casing beyond simple camelCase.
+_ABBREV_MAP: dict[str, str] = {"deviceUrl": "deviceURL"}
+
+
+def _fix_abbreviations(obj: Any) -> Any:
+    if isinstance(obj, dict):
+        out = {}
+        for k, v in obj.items():
+            k = _ABBREV_MAP.get(k, k)
+            out[k] = _fix_abbreviations(v)
+        return out
+    if isinstance(obj, list):
+        return [_fix_abbreviations(i) for i in obj]
+    return obj
+
+
+def prepare_payload(payload: Any) -> Any:
+    """Convert snake_case payload to API-ready camelCase and apply fixes.
+
+    Example:
+        payload = {"device_url": "x", "commands": [{"name": "close"}]}
+        => {"deviceURL": "x", "commands": [{"name": "close"}]}
+    """
+    camel = humps.camelize(payload)
+    return _fix_abbreviations(camel)

tests/test_client.py

@@ -363,6 +363,41 @@ async def test_get_setup_options(
             for option in options:
                 assert isinstance(option, Option)
 
+    @pytest.mark.asyncio
+    async def test_execute_action_group_omits_none_fields(self, client: OverkizClient):
+        """Ensure `type` and `parameters` that are None are omitted from the request payload."""
+        from pyoverkiz.enums.command import OverkizCommand
+        from pyoverkiz.models import Action, Command
+
+        action = Action(
+            "rts://2025-8464-6867/16756006",
+            [Command(name=OverkizCommand.CLOSE, parameters=None, type=None)],
+        )
+
+        resp = MockResponse('{"execId": "exec-123"}')
+
+        with patch.object(aiohttp.ClientSession, "post") as mock_post:
+            mock_post.return_value = resp
+
+            exec_id = await client.execute_action_group([action])
+
+            assert exec_id == "exec-123"
+
+            assert mock_post.called
+            _, kwargs = mock_post.call_args
+            sent_json = kwargs.get("json")
+            assert sent_json is not None
+
+            # The client should have converted payload to camelCase and applied
+            # abbreviation fixes (deviceURL) before sending.
+            action_sent = sent_json["actions"][0]
+            assert action_sent.get("deviceURL") == action.device_url
+
+            cmd = action_sent["commands"][0]
+            assert "type" not in cmd
+            assert "parameters" not in cmd
+            assert cmd["name"] == "close"
+
     @pytest.mark.parametrize(
         "fixture_name, option_name, instance",
         [

tests/test_models.py

@@ -274,3 +274,31 @@ def test_bad_list_value(self):
         state = State(name="state", type=DataType.BOOLEAN, value=False)
         with pytest.raises(TypeError):
             assert state.value_as_list
+
+
+def test_command_to_payload_omits_none():
+    from pyoverkiz.enums.command import OverkizCommand
+    from pyoverkiz.models import Command
+
+    cmd = Command(name=OverkizCommand.CLOSE, parameters=None, type=None)
+    payload = cmd.to_payload()
+
+    assert payload == {"name": "close"}
+
+
+def test_action_to_payload_and_parameters_conversion():
+    from pyoverkiz.enums.command import OverkizCommand, OverkizCommandParam
+    from pyoverkiz.models import Action, Command
+
+    cmd = Command(
+        name=OverkizCommand.SET_LEVEL, parameters=[10, OverkizCommandParam.A], type=1
+    )
+    action = Action("rts://2025-8464-6867/16756006", [cmd])
+
+    payload = action.to_payload()
+
+    assert payload["device_url"] == "rts://2025-8464-6867/16756006"
+    assert payload["commands"][0]["name"] == "setLevel"
+    assert payload["commands"][0]["type"] == 1
+    # parameters should be converted to primitives (enum -> str)
+    assert payload["commands"][0]["parameters"] == [10, "A"]

tests/test_serializers.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pyoverkiz.serializers import prepare_payload
+
+
+def test_prepare_payload_camelizes_and_fixes_device_url():
+    payload = {
+        "label": "test",
+        "actions": [{"device_url": "rts://1/2", "commands": [{"name": "close"}]}],
+    }
+
+    final = prepare_payload(payload)
+
+    assert final["label"] == "test"
+    assert "deviceURL" in final["actions"][0]
+    assert final["actions"][0]["deviceURL"] == "rts://1/2"
+
+
+def test_prepare_payload_nested_lists_and_dicts():
+    payload = {
+        "actions": [
+            {
+                "device_url": "rts://1/2",
+                "commands": [{"name": "setLevel", "parameters": [10, "A"]}],
+            }
+        ]
+    }
+
+    final = prepare_payload(payload)
+
+    cmd = final["actions"][0]["commands"][0]
+    assert cmd["name"] == "setLevel"
+    assert cmd["parameters"] == [10, "A"]