feat: auto-create timer helpers transparently on first action

Timer entities now automatically create the HA helper via the
timer/create WS command when an action method is called and the
entity has not yet been seen from Home Assistant. This removes
the need for users to pre-create timer helpers manually.

Also adds Timer.delete() for cleanup and resets the ensured flag
so subsequent actions re-create the helper if needed.

Author: Faerkeren

src/haclient/domains/timer.py

@@ -18,6 +18,12 @@ class Timer(Entity):
     Actions use intent-specific names: ``start``, ``pause``, ``cancel``,
     ``finish``, ``change``.
 
+    If the timer helper does not yet exist in Home Assistant, it is created
+    automatically via the ``timer/create`` WebSocket command the first time
+    an action method (``start``, ``pause``, etc.) is called.  This means
+    users never need to pre-create timer helpers — the library handles it
+    transparently.
+
     In addition to the generic ``on_idle`` listener (which fires for both
     natural expiry and explicit cancellation), the timer provides
     ``on_finished`` and ``on_cancelled`` listeners that fire only for the
@@ -35,6 +41,7 @@ def __init__(self, entity_id: str, client: Any) -> None:
         super().__init__(entity_id, client)
         self._finished_listeners: list[ValueChangeHandler] = []
         self._cancelled_listeners: list[ValueChangeHandler] = []
+        self._ensured: bool = False
 
     # -- State properties --
 
@@ -141,6 +148,51 @@ def time_remaining(self) -> float | None:
             return _parse_duration_to_seconds(str(raw))
         return None
 
+    # -- Lifecycle --
+
+    async def _ensure_exists(self) -> None:
+        """Create the timer helper in Home Assistant if it does not exist.
+
+        Uses the ``timer/create`` WebSocket command.  The call is idempotent:
+        once the helper has been confirmed (either via the initial state fetch
+        or a prior ``_ensure_exists`` call), subsequent invocations are no-ops.
+
+        The object-id is extracted from the ``entity_id`` (the part after
+        ``timer.``).
+        """
+        if self._ensured or self.state != "unknown":
+            return
+        object_id = self.entity_id.split(".", 1)[1]
+        await self._client.ws.send_command(
+            {
+                "type": "timer/create",
+                "name": object_id,
+                "duration": "00:01:00",
+            }
+        )
+        self._ensured = True
+
+    async def delete(self) -> None:
+        """Delete the timer helper from Home Assistant.
+
+        Uses the ``timer/delete`` WebSocket command.  After deletion the
+        entity's ``_ensured`` flag is reset so that a subsequent action
+        will re-create the helper.
+
+        Raises
+        ------
+        CommandError
+            If the timer does not exist in Home Assistant.
+        """
+        object_id = self.entity_id.split(".", 1)[1]
+        await self._client.ws.send_command(
+            {
+                "type": "timer/delete",
+                "timer_id": object_id,
+            }
+        )
+        self._ensured = False
+
     # -- Actions --
 
     async def start(self, *, duration: str | None = None) -> None:
@@ -151,19 +203,23 @@ async def start(self, *, duration: str | None = None) -> None:
         duration : str or None, optional
             Override duration (e.g. ``"00:05:00"``).
         """
+        await self._ensure_exists()
         data: dict[str, Any] | None = {"duration": duration} if duration else None
         await self._call_service("start", data)
 
     async def pause(self) -> None:
         """Pause the timer."""
+        await self._ensure_exists()
         await self._call_service("pause")
 
     async def cancel(self) -> None:
         """Cancel the timer (returns to idle)."""
+        await self._ensure_exists()
         await self._call_service("cancel")
 
     async def finish(self) -> None:
         """Finish the timer immediately."""
+        await self._ensure_exists()
         await self._call_service("finish")
 
     async def change(self, *, duration: str) -> None:
@@ -174,6 +230,7 @@ async def change(self, *, duration: str) -> None:
         duration : str
             Duration to add/subtract (e.g. ``"00:01:00"`` or ``"-00:00:30"``).
         """
+        await self._ensure_exists()
         await self._call_service("change", {"duration": duration})
 
     # -- Listener decorators --

tests/fake_ha.py

@@ -190,6 +190,33 @@ async def _dispatch(self, ws: web.WebSocketResponse, msg: dict[str, Any]) -> Non
         if mtype == "media_player/browse_media":
             await ws.send_json({"id": mid, "type": "result", "success": True, "result": {}})
             return
+        if mtype == "timer/create":
+            name = msg.get("name", "")
+            duration = msg.get("duration", "00:01:00")
+            await ws.send_json(
+                {
+                    "id": mid,
+                    "type": "result",
+                    "success": True,
+                    "result": {
+                        "id": name,
+                        "name": name,
+                        "duration": duration,
+                        "restore": False,
+                    },
+                }
+            )
+            return
+        if mtype == "timer/delete":
+            await ws.send_json(
+                {
+                    "id": mid,
+                    "type": "result",
+                    "success": True,
+                    "result": None,
+                }
+            )
+            return
 
         await ws.send_json(
             {

tests/test_timer_lifecycle.py

@@ -0,0 +1,108 @@
+"""Tests for Timer auto-create and delete lifecycle."""
+
+from __future__ import annotations
+
+from haclient import HAClient
+
+from .fake_ha import FakeHA
+
+
+async def test_timer_start_auto_creates_when_unknown(client: HAClient, fake_ha: FakeHA) -> None:
+    """Calling start() on a timer with state 'unknown' should send timer/create first."""
+    t = client.timer("my_timer")
+    assert t.state == "unknown"
+
+    await t.start(duration="00:00:10")
+
+    # The timer/create command should have been sent (check ws_service_calls
+    # won't capture it — we need to check via the call_service call that followed).
+    # The call_service for timer.start should be present.
+    assert len(fake_ha.ws_service_calls) == 1
+    call = fake_ha.ws_service_calls[0]
+    assert call["domain"] == "timer"
+    assert call["service"] == "start"
+    assert t._ensured is True
+
+
+async def test_timer_start_skips_create_when_state_known(client: HAClient, fake_ha: FakeHA) -> None:
+    """If the timer already has a state from HA, _ensure_exists is a no-op."""
+    t = client.timer("my_timer")
+    # Simulate that HA already reported the entity's state.
+    t._apply_state({"state": "idle", "attributes": {"duration": "0:01:00"}})
+    assert t.state == "idle"
+
+    await t.start(duration="00:00:10")
+
+    # Only the service call, no timer/create.
+    assert len(fake_ha.ws_service_calls) == 1
+    call = fake_ha.ws_service_calls[0]
+    assert call["domain"] == "timer"
+    assert call["service"] == "start"
+
+
+async def test_timer_ensure_exists_only_called_once(client: HAClient, fake_ha: FakeHA) -> None:
+    """After the first _ensure_exists succeeds, subsequent calls are no-ops."""
+    t = client.timer("my_timer")
+    assert t.state == "unknown"
+
+    await t.start(duration="00:00:10")
+    await t.pause()
+
+    # Both actions should fire, but timer/create only once.
+    assert len(fake_ha.ws_service_calls) == 2
+    assert t._ensured is True
+
+
+async def test_timer_pause_auto_creates(client: HAClient, fake_ha: FakeHA) -> None:
+    """pause() should also trigger auto-create."""
+    t = client.timer("my_timer")
+    await t.pause()
+    assert t._ensured is True
+    assert len(fake_ha.ws_service_calls) == 1
+
+
+async def test_timer_cancel_auto_creates(client: HAClient, fake_ha: FakeHA) -> None:
+    """cancel() should also trigger auto-create."""
+    t = client.timer("my_timer")
+    await t.cancel()
+    assert t._ensured is True
+
+
+async def test_timer_finish_auto_creates(client: HAClient, fake_ha: FakeHA) -> None:
+    """finish() should also trigger auto-create."""
+    t = client.timer("my_timer")
+    await t.finish()
+    assert t._ensured is True
+
+
+async def test_timer_change_auto_creates(client: HAClient, fake_ha: FakeHA) -> None:
+    """change() should also trigger auto-create."""
+    t = client.timer("my_timer")
+    await t.change(duration="00:00:30")
+    assert t._ensured is True
+
+
+async def test_timer_delete(client: HAClient, fake_ha: FakeHA) -> None:
+    """delete() sends timer/delete and resets _ensured."""
+    t = client.timer("my_timer")
+    # First ensure it exists.
+    await t.start()
+    assert t._ensured is True
+
+    await t.delete()
+    assert t._ensured is False
+
+
+async def test_timer_delete_then_start_recreates(client: HAClient, fake_ha: FakeHA) -> None:
+    """After delete(), the next action should re-create the timer."""
+    t = client.timer("my_timer")
+    await t.start()
+    assert t._ensured is True
+
+    await t.delete()
+    assert t._ensured is False
+
+    # Reset state to unknown to simulate the entity being gone.
+    t.state = "unknown"
+    await t.start()
+    assert t._ensured is True