Fix RTS duration injection and add comprehensive tests (#2068)

## Summary

- **Fixes the RTS duration injection logic** to correctly handle
multi-param commands like `tiltPositive` and `moveOf` based on the
Overkiz API documentation
- **Renames `rts_command_duration` to `default_rts_command_duration`**
to make clear it's a default that users can override by passing the
duration themselves
- **Adds 50 tests** covering all RTS injection scenarios

## Problem

The original implementation used `current_count < nparams` which would
incorrectly inject duration into domain-specific parameter slots. For
example, `tiltPositive(nparams=2)` called with only 1 param would get
duration injected as the position value.

## Fix

Per the Overkiz API docs, the **last parameter of every RTS command is
always the execution duration**. The correct injection rule is
`current_count == nparams - 1` — only inject when all domain-specific
params are filled and exactly the duration slot remains empty.

| Command | nparams | Last param | Injection behavior |
|---------|---------|------------|--------------------|
| `close`, `open`, `up`, `down`, `stop`, `my`, `rest` | 1 | duration
(default 30s) | Injected when called with no args |
| `tiltPositive`, `tiltNegative`, `moveOf` | 2 | duration (default 15s)
| Injected when called with position arg only |
| `identify`, `test` | 0 | — | Never injected |

If a user explicitly provides the duration parameter, their value is
never overwritten.

## Test plan

- [x] All 50 RTS injection tests pass
- [x] Full test suite (480 tests) passes
- [x] mypy and ty type checking pass
- [ ] Verify HA integration works with renamed
`default_rts_command_duration` setting

Author: iMicknl

docs/device-control.md

@@ -294,7 +294,9 @@ trigger_id = await client.schedule_persisted_action_group(
 
 ## RTS command duration
 
-RTS devices have a default execution duration of 30 seconds, which blocks consecutive commands until the duration expires. To avoid this, you can configure `rts_command_duration` in `OverkizClientSettings`. The client will automatically inject the configured duration into RTS commands that support it, based on the command definition (`nparams`).
+For RTS commands, the **last parameter is always the execution duration** (defaults to 15–30 seconds depending on the command). This blocks consecutive commands until the duration expires.
+
+You can configure `default_rts_command_duration` in `OverkizClientSettings` to override this default. The client injects this value as the duration parameter only when the user has not already provided it explicitly.
 
 ```python
 from pyoverkiz.auth.credentials import UsernamePasswordCredentials
@@ -305,11 +307,19 @@ from pyoverkiz.enums import Server
 client = OverkizClient(
     server=Server.SOMFY_EUROPE,
     credentials=UsernamePasswordCredentials("user@example.com", "password"),
-    settings=OverkizClientSettings(rts_command_duration=0),
+    settings=OverkizClientSettings(default_rts_command_duration=0),
 )
 ```
 
-With `rts_command_duration=0`, the execution duration is set to 0 seconds for supported commands, allowing consecutive commands to be sent without delay. Commands that don't accept a duration parameter (like `identify` or `test`) are left unchanged.
+With `default_rts_command_duration=0`, consecutive commands can be sent without delay. If a user passes the duration explicitly (e.g., `Command(name="close", parameters=[5])`), their value takes precedence.
+
+| Command | nparams | Last param | Injection behavior |
+|---------|---------|------------|--------------------|
+| `close`, `open`, `up`, `down`, `stop`, `my`, `rest` | 1 | duration (default 30s) | Injected when called with no args |
+| `tiltPositive`, `tiltNegative`, `moveOf` | 2 | duration (default 15s) | Injected when called with position arg only |
+| `identify`, `test` | 0 | — | Never injected (no parameters) |
+
+The injection rule: duration is injected only when all domain-specific parameters have been provided but the duration slot is still empty (`current_count == nparams - 1`). If the user already provides the duration themselves, the configured default is not applied.
 
 ## Limitations and rate limits
 

docs/migration-v2.md

@@ -406,7 +406,7 @@ These are not breaking, but worth knowing about when migrating:
 
 - **Client settings** — behavioral configuration is now grouped in `OverkizClientSettings`, passed via the `settings` parameter. This replaces standalone constructor parameters like `action_queue`.
 - **Action queue** — batch device executions automatically. See the [action queue guide](action-queue.md).
-- **RTS command duration** — automatically inject execution duration into RTS commands to prevent the default 30-second blocking behavior. See [RTS command duration](device-control.md#rts-command-duration).
+- **RTS command duration** — override the default execution duration for RTS commands (15–30s) to prevent blocking consecutive commands. See [RTS command duration](device-control.md#rts-command-duration).
 - **Device helpers** — `Device.get_command_definition()` for looking up command metadata.
 - **Reference endpoints** — query server metadata: `get_reference_ui_classes()`, `get_reference_ui_widgets()`, `get_reference_ui_profile()`, `get_reference_controllable_types()`, etc.
 - **Firmware management** — `get_devices_not_up_to_date()`, `get_device_firmware_status()`, `update_device_firmware()`.

pyoverkiz/client.py

@@ -171,7 +171,7 @@ class OverkizClientSettings:
     """
 
     action_queue: ActionQueueSettings | None = None
-    rts_command_duration: int | None = None
+    default_rts_command_duration: int | None = None
 
 
 class OverkizClient:
@@ -513,14 +513,19 @@ async def get_api_version(self) -> str:
         return cast(str, response["protocolVersion"])
 
     def _apply_rts_duration(self, actions: list[Action]) -> list[Action]:
-        """Set the execution duration for RTS commands that support it.
+        """Apply the default execution duration for RTS commands.
 
-        The default execution duration for RTS devices is 30 seconds, which
-        blocks consecutive commands. This injects the configured duration
-        (typically 0) into commands that accept it, based on the device
-        command definition (nparams).
+        For RTS commands, the last parameter is always the execution duration
+        (default 15s for tilt commands, 30s for movement commands). This
+        injects ``default_rts_command_duration`` as the last parameter only
+        when the user has not already provided it — i.e., when the command
+        has all domain-specific parameters filled but the duration slot is
+        still empty (current_count == nparams - 1).
+
+        If the user explicitly passes the duration parameter themselves, it
+        is left unchanged.
         """
-        duration = self.settings.rts_command_duration
+        duration = self.settings.default_rts_command_duration
         if duration is None:
             return actions
 
@@ -539,7 +544,11 @@ def _apply_rts_duration(self, actions: list[Action]) -> list[Action]:
                 cmd_def = device.get_command_definition(str(cmd.name))
                 current_count = len(cmd.parameters) if cmd.parameters else 0
 
-                if cmd_def and current_count < cmd_def.nparams:
+                if (
+                    cmd_def
+                    and cmd_def.nparams > 0
+                    and current_count == cmd_def.nparams - 1
+                ):
                     updated_commands.append(
                         Command(
                             name=cmd.name,

tests/test_client.py

@@ -1235,17 +1235,17 @@ class TestOverkizClientSettings:
     def test_client_with_settings_none(self, client: OverkizClient) -> None:
         """Client without settings has no action queue and no RTS duration."""
         assert client._action_queue is None
-        assert client.settings.rts_command_duration is None
+        assert client.settings.default_rts_command_duration is None
 
     @pytest.mark.asyncio
     async def test_client_with_rts_duration(self) -> None:
         """Client stores RTS command duration from settings."""
         client = OverkizClient(
             server=Server.SOMFY_EUROPE,
             credentials=UsernamePasswordCredentials("user", "pass"),
-            settings=OverkizClientSettings(rts_command_duration=0),
+            settings=OverkizClientSettings(default_rts_command_duration=0),
         )
-        assert client.settings.rts_command_duration == 0
+        assert client.settings.default_rts_command_duration == 0
 
     @pytest.mark.asyncio
     async def test_client_with_action_queue_via_settings(self) -> None:

tests/test_client_settings.py

@@ -8,13 +8,13 @@ def test_defaults():
     """Default settings have no queue and no RTS duration."""
     settings = OverkizClientSettings()
     assert settings.action_queue is None
-    assert settings.rts_command_duration is None
+    assert settings.default_rts_command_duration is None
 
 
 def test_with_rts_duration():
     """RTS command duration can be set."""
-    settings = OverkizClientSettings(rts_command_duration=0)
-    assert settings.rts_command_duration == 0
+    settings = OverkizClientSettings(default_rts_command_duration=0)
+    assert settings.default_rts_command_duration == 0
 
 
 def test_with_action_queue_settings():