ha-mcp-dev 9.1.1.dev3362__tar.gz → 9.1.1.dev3365__tar.gz

{ha_mcp_dev-9.1.1.dev3362 → ha_mcp_dev-9.1.1.dev3365}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.1.dev3362
+Version: 9.1.1.dev3365
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.1.1.dev3362 → ha_mcp_dev-9.1.1.dev3365}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.1.dev3362"
+version = "9.1.1.dev3365"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.1.dev3362 → ha_mcp_dev-9.1.1.dev3365}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.1.dev3362"
+version = "9.1.1.dev3365"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

ha_mcp_dev-9.1.1.dev3365/src/ha_mcp/backup_calendar.py

@@ -0,0 +1,283 @@
+"""Auto-backup handlers for calendar events.
+
+A snapshot holds one event (or one occurrence) read from the calendar view; a
+restore puts it back in place by uid, or re-creates a deleted event.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from .backup_entity_ids import _manager
+from .client.rest_client import HomeAssistantCommandError, HomeAssistantError
+
+logger = logging.getLogger(__name__)
+
+
+# Wide enough for past and far-booked events without expanding years of recurrences.
+_CALENDAR_WIDE_LOOKBACK_DAYS = 366
+_CALENDAR_WIDE_LOOKAHEAD_DAYS = 732
+
+
+async def _find_calendar_event(
+    client: Any,
+    cal: str,
+    uid: str,
+    recurrence_id: str | None,
+    start: datetime,
+    end: datetime,
+) -> Any:
+    """The ``uid`` event (occurrence ``recurrence_id``) on ``cal`` in the window.
+
+    The REST calendar view, not ``calendar.get_events``: the service drops uid.
+    """
+    try:
+        events = await client._request(
+            "GET",
+            f"/calendars/{cal}",
+            params={"start": start.isoformat(), "end": end.isoformat()},
+        )
+    except HomeAssistantError as err:
+        # 404: the calendar integration is not loaded.
+        if getattr(err, "status_code", None) == 404:
+            return None
+        raise
+    for event in _manager()._require_list(events, f"/calendars/{cal}"):
+        if not isinstance(event, dict) or event.get("uid") != uid:
+            continue
+        if recurrence_id is not None and event.get("recurrence_id") != recurrence_id:
+            continue
+        return event
+    return None
+
+
+def _day_window(value: str | None) -> tuple[datetime, datetime] | None:
+    """A day either side of a recurrence id or ISO date(-time), if it parses."""
+    try:
+        at = datetime.fromisoformat(value or "")
+    except ValueError:
+        return None
+    at = at if at.tzinfo else at.replace(tzinfo=UTC)
+    return at - timedelta(days=1), at + timedelta(days=1)
+
+
+async def _locate_calendar_event(
+    client: Any, cal: str, uid: str, wanted: str | None, near: str | None = None
+) -> Any:
+    """The ``uid`` event (occurrence ``wanted``) on ``cal``; None if no window has it.
+
+    Out-of-window events and cancelled ones Local Calendar hides also read as None.
+    """
+    try:
+        from .config import get_global_settings
+
+        days = int(
+            getattr(get_global_settings(), "auto_backup_calendar_lookahead_days", 7)
+        )
+    except (AttributeError, ImportError, ValueError, TypeError):
+        days = 7
+    days = max(1, min(365, days))
+    now = datetime.now(UTC)
+    # A recurrence_id names the occurrence's date; without one, ``near`` (the
+    # snapshot's start) places the request that finds an event the windows
+    # below would miss.
+    around = _day_window(wanted) or _day_window(near)
+    found = (
+        await _find_calendar_event(client, cal, uid, wanted, *around)
+        if around
+        else None
+    )
+    if found is None:
+        found = await _find_calendar_event(
+            client, cal, uid, wanted, now, now + timedelta(days=days)
+        )
+    if found is None:
+        # A missed event would skip the snapshot or be re-created on restore.
+        found = await _find_calendar_event(
+            client,
+            cal,
+            uid,
+            wanted,
+            now - timedelta(days=_CALENDAR_WIDE_LOOKBACK_DAYS),
+            now + timedelta(days=_CALENDAR_WIDE_LOOKAHEAD_DAYS),
+        )
+    return found
+
+
+async def _fetch_calendar_event(client: Any, entity_id: str) -> Any:
+    # "<calendar.entity>::<event_uid>[::<recurrence_id>]"
+    cal, _, rest = entity_id.partition("::")
+    uid, _, recurrence_id = rest.partition("::")
+    if not cal or not uid:
+        return None
+    wanted = recurrence_id or None
+    found = await _locate_calendar_event(client, cal, uid, wanted)
+    if found is None:
+        return None
+    if wanted is None and found.get("rrule"):
+        # The view shows only expanded occurrences, never the series itself,
+        # so a series-wide write cannot be restored faithfully.
+        logger.warning(
+            "Auto-backup: no snapshot for series-wide write on %s (event %s); "
+            "Home Assistant exposes only expanded occurrences, so the series "
+            "could not be restored faithfully",
+            cal,
+            uid,
+        )
+        return None
+    return {"calendar_entity_id": cal, **found}
+
+
+def _calendar_bound(value: Any) -> tuple[str, bool] | None:
+    """``(iso_value, is_date_only)``; older snapshots hold a flat ISO string."""
+    if isinstance(value, dict):
+        if value.get("dateTime"):
+            return str(value["dateTime"]), False
+        if value.get("date"):
+            return str(value["date"]), True
+        return None
+    if isinstance(value, str) and value:
+        return value, len(value) == 10
+    return None
+
+
+def _same_bound(found: tuple[str, bool] | None, wanted: tuple[str, bool]) -> bool:
+    """Equal bounds: timed ones by instant, or by wall clock, which Local
+    Calendar's floating times keep across a timezone change."""
+    if found is None or found[1] != wanted[1]:
+        return False
+    if found[1] or found[0] == wanted[0]:
+        return found[0] == wanted[0]
+    at, want = datetime.fromisoformat(found[0]), datetime.fromisoformat(wanted[0])
+    if at.replace(tzinfo=None) == want.replace(tzinfo=None):
+        return True
+    return at.tzinfo is not None and want.tzinfo is not None and at == want
+
+
+async def _restored_copy(
+    client: Any,
+    cal: str,
+    event: dict[str, Any],
+    start: tuple[str, bool],
+    end: tuple[str, bool],
+) -> dict[str, Any] | None:
+    """The copy an earlier restore re-created: same summary, times and text.
+
+    A re-created event gets a new uid, so its snapshot's uid stays gone. A day
+    either side covers a timezone change since the copy was made.
+    """
+    first, last = (
+        datetime.fromisoformat(f"{value}T00:00:00" if date_only else value)
+        for value, date_only in (start, end)
+    )
+    try:
+        events = await client._request(
+            "GET",
+            f"/calendars/{cal}",
+            params={
+                "start": (first - timedelta(days=1)).isoformat(),
+                "end": (last + timedelta(days=1)).isoformat(),
+            },
+        )
+    except HomeAssistantError as err:
+        if getattr(err, "status_code", None) == 404:
+            return None
+        raise
+    for found in _manager()._require_list(events, f"/calendars/{cal}"):
+        if (
+            isinstance(found, dict)
+            and _same_bound(_calendar_bound(found.get("start")), start)
+            and _same_bound(_calendar_bound(found.get("end")), end)
+            and all(
+                (found.get(key) or "") == event[key]
+                for key in ("summary", "description", "location")
+            )
+        ):
+            return found
+    return None
+
+
+async def _recreate_calendar_event(
+    client: Any,
+    cal: str,
+    event: dict[str, Any],
+    start: tuple[str, bool],
+    end: tuple[str, bool],
+) -> Any:
+    """Re-create a deleted event, always as a single event."""
+    if (copy := await _restored_copy(client, cal, event, start, end)) is not None:
+        return {"already_restored": True, "event": copy}
+    data: dict[str, Any] = {"entity_id": cal, "summary": event["summary"]}
+    if start[1]:
+        data.update({"start_date": start[0], "end_date": end[0]})
+    else:
+        data.update({"start_date_time": start[0], "end_date_time": end[0]})
+    for key in ("description", "location"):
+        if event.get(key):
+            data[key] = event[key]
+    return await _manager()._rest_post(client, "services/calendar/create_event", data)
+
+
+async def _restore_calendar_event(client: Any, entity_id: str, config: Any) -> Any:
+    cal, _, rest = entity_id.partition("::")
+    key_uid, _, key_recurrence_id = rest.partition("::")
+    cal = config.get("calendar_entity_id") or cal
+    uid = config.get("uid") or key_uid
+    recurrence_id = config.get("recurrence_id") or key_recurrence_id or None
+    start = _calendar_bound(config.get("start"))
+    end = _calendar_bound(config.get("end"))
+    if start is None or end is None:
+        raise HomeAssistantError(
+            f"Calendar snapshot for {entity_id!r} has no usable start/end"
+        )
+
+    # Core merges an update into the stored event: empty text clears a field.
+    event: dict[str, Any] = {
+        "summary": config.get("summary") or "",
+        "dtstart": start[0],
+        "dtend": end[0],
+        "description": config.get("description") or "",
+        "location": config.get("location") or "",
+    }
+    # No rrule: on one occurrence it would start a second series under the uid.
+
+    if not uid:
+        return await _recreate_calendar_event(client, cal, event, start, end)
+
+    message: dict[str, Any] = {
+        "type": "calendar/event/update",
+        "entity_id": cal,
+        "uid": uid,
+        "event": event,
+    }
+    if recurrence_id:
+        message["recurrence_id"] = recurrence_id
+    try:
+        return await _manager()._ws_send(client, message)
+    except HomeAssistantCommandError as err:
+        unsupported = err.code == "not_supported"
+        # Local Calendar reports a missing event as a generic ``failed``, so
+        # only that code is checked against the calendar before re-creating.
+        if not unsupported and (
+            err.code != "failed"
+            or await _locate_calendar_event(client, cal, uid, recurrence_id, start[0])
+            is not None
+        ):
+            raise
+        if recurrence_id:
+            # create_event can only add a detached event, not the occurrence.
+            cause = "cannot be updated" if unsupported else "no longer exists"
+            raise HomeAssistantError(
+                f"Occurrence {recurrence_id} of event {uid} {cause} on {cal}, "
+                "and an occurrence cannot be re-created into its series"
+            ) from err
+        logger.info(
+            "Restoring calendar event %s on %s in place is not possible (%s); "
+            "re-creating it under a new uid instead",
+            uid,
+            cal,
+            err,
+        )
+    return await _recreate_calendar_event(client, cal, event, start, end)

{ha_mcp_dev-9.1.1.dev3362 → ha_mcp_dev-9.1.1.dev3365}/src/ha_mcp/backup_manager.py

@@ -56,7 +56,7 @@ from collections import Counter
 from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import asynccontextmanager, suppress
 from dataclasses import dataclass, field
-from datetime import UTC, datetime, timedelta
+from datetime import UTC, datetime
 from functools import cached_property, partial
 from pathlib import Path
 from typing import Any, Literal, NotRequired, TypedDict
@@ -66,6 +66,7 @@ import yaml  # type: ignore[import-untyped]
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
 from ha_mcp._vendor.websockets.exceptions import ConnectionClosed
 
+from .backup_calendar import _fetch_calendar_event, _restore_calendar_event
 from .backup_dashboards import (
     _DASHBOARD_KIND,
     dashboard_comparison,
@@ -2314,276 +2315,6 @@ async def _restore_group(client: Any, entity_id: str, config: Any) -> Any:
     return await _ws_send(client, {**group_set, "service_data": service_data})
 
 
-# Calendar events — calendar.get_events to fetch, calendar.create/update services.
-
-
-# Bounds of the second sweep below: wide enough for a past event or one booked
-# well ahead, without asking a busy calendar to expand a decade of recurrences.
-_CALENDAR_WIDE_LOOKBACK_DAYS = 366
-_CALENDAR_WIDE_LOOKAHEAD_DAYS = 732
-
-
-async def _find_calendar_event(
-    client: Any,
-    cal: str,
-    uid: str,
-    recurrence_id: str | None,
-    start: datetime,
-    end: datetime,
-) -> Any:
-    """Return the event with ``uid`` on ``cal`` between ``start`` and ``end``.
-
-    Reads the REST calendar view rather than the ``calendar.get_events``
-    service: the service response is built by HA's
-    ``_list_events_dict_factory``, which keeps only ``LIST_EVENT_FIELDS``
-    (start/end/summary/description/location/status) and therefore carries no
-    ``uid`` to match on. ``/api/calendars/{entity_id}`` serialises the whole
-    CalendarEvent, so uid, recurrence_id and rrule survive — the same endpoint
-    ``ha_config_get_calendar_events`` reads.
-
-    A recurring series is expanded into occurrences that all share the ``uid``,
-    so ``recurrence_id`` selects which one; without it the first match wins.
-    """
-    try:
-        events = await client._request(
-            "GET",
-            f"/calendars/{cal}",
-            params={"start": start.isoformat(), "end": end.isoformat()},
-        )
-    except HomeAssistantError as err:
-        # Only treat 404 (calendar entity not present) as "skip silently".
-        # Auth/transport/server errors deserve a WARNING so an operator
-        # can spot a misconfigured calendar integration; matches the
-        # ``status_code == 404`` narrowing the automation/script/scene
-        # fetchers use.
-        if getattr(err, "status_code", None) == 404:
-            return None
-        raise
-    for event in _require_list(events, f"/calendars/{cal}"):
-        if not isinstance(event, dict) or event.get("uid") != uid:
-            continue
-        if recurrence_id is not None and event.get("recurrence_id") != recurrence_id:
-            continue
-        return event
-    return None
-
-
-def _recurrence_id_window(
-    recurrence_id: str | None,
-) -> tuple[datetime, datetime] | None:
-    """A day-wide window around an iCalendar recurrence id, if it parses."""
-    if not recurrence_id:
-        return None
-    for fmt in ("%Y%m%dT%H%M%S", "%Y%m%dT%H%M%SZ", "%Y%m%d"):
-        try:
-            at = datetime.strptime(recurrence_id, fmt).replace(tzinfo=UTC)
-        except ValueError:
-            continue
-        return at - timedelta(days=1), at + timedelta(days=1)
-    return None
-
-
-async def _fetch_calendar_event(client: Any, entity_id: str) -> Any:
-    # entity_id is "<calendar.entity>::<event_uid>[::<recurrence_id>]"
-    cal, _, rest = entity_id.partition("::")
-    uid, _, recurrence_id = rest.partition("::")
-    if not cal or not uid:
-        return None
-    # Configurable lookahead window. Default 7 days catches typical edits;
-    # set HAMCP_AUTO_BACKUP_CALENDAR_LOOKAHEAD_DAYS to widen for far-future
-    # events or narrow to skip noise. Bounded so a typo can't query
-    # decades of history.
-    try:
-        from .config import get_global_settings
-
-        days = int(
-            getattr(get_global_settings(), "auto_backup_calendar_lookahead_days", 7)
-        )
-    except (AttributeError, ImportError, ValueError, TypeError):
-        days = 7
-    days = max(1, min(365, days))
-    now = datetime.now(UTC)
-    wanted = recurrence_id or None
-    # A recurrence_id names the occurrence's own date, so an occurrence far
-    # outside the windows below is still found in one request.
-    around = _recurrence_id_window(wanted)
-    found = (
-        await _find_calendar_event(client, cal, uid, wanted, *around)
-        if around
-        else None
-    )
-    if found is None:
-        found = await _find_calendar_event(
-            client, cal, uid, wanted, now, now + timedelta(days=days)
-        )
-    if found is None:
-        # The configured window is the cheap common case, not the contract: a
-        # write targets an event by uid, and an event being edited or deleted
-        # can sit in the past or well beyond the lookahead. Missing it would
-        # silently skip the snapshot and leave the prior values unrecoverable,
-        # so sweep once more over a wide window before concluding it is gone.
-        found = await _find_calendar_event(
-            client,
-            cal,
-            uid,
-            wanted,
-            now - timedelta(days=_CALENDAR_WIDE_LOOKBACK_DAYS),
-            now + timedelta(days=_CALENDAR_WIDE_LOOKAHEAD_DAYS),
-        )
-    if found is None:
-        return None
-    if wanted is None and found.get("rrule"):
-        # The write targets a whole series, but the calendar view only exposes
-        # expanded OCCURRENCES — never the master event's own start. Restoring
-        # one occurrence's values would revert a single date and leave the rest
-        # of the series edited, or re-create a series starting at the wrong
-        # date, both reported as a successful restore. No snapshot is the
-        # honest answer; a single-occurrence write (which carries a
-        # recurrence_id) is captured normally.
-        logger.warning(
-            "Auto-backup: no snapshot for series-wide write on %s (event %s); "
-            "Home Assistant exposes only expanded occurrences, so the series "
-            "could not be restored faithfully",
-            cal,
-            uid,
-        )
-        return None
-    return {"calendar_entity_id": cal, **found}
-
-
-def _calendar_bound(value: Any) -> tuple[str, bool] | None:
-    """Return ``(iso_value, is_date_only)`` for a snapshotted event boundary.
-
-    The REST view wraps each boundary as ``{"dateTime": ...}`` (timed) or
-    ``{"date": ...}`` (all-day); snapshots taken before that switch hold a
-    flat ISO string, which a 10-character length identifies as date-only.
-    """
-    if isinstance(value, dict):
-        if value.get("dateTime"):
-            return str(value["dateTime"]), False
-        if value.get("date"):
-            return str(value["date"]), True
-        return None
-    if isinstance(value, str) and value:
-        return value, len(value) == 10
-    return None
-
-
-# HA reports a missing event as a plain ``failed`` command error whose message
-# comes from the integration (Local Calendar surfaces ical's "No existing item
-# with uid/recurrence_id: ..."), so absence has to be read off the message.
-_CALENDAR_EVENT_ABSENT_MARKERS = ("no existing item", "not found", "does not exist")
-
-
-def _calendar_update_cannot_apply(err: HomeAssistantCommandError) -> bool:
-    """Whether ``err`` proves the in-place update never touched the event."""
-    if getattr(err, "code", None) == "not_supported":
-        # The calendar advertises no UPDATE_EVENT, so it cannot ever accept
-        # the update and re-creating is the only restore available.
-        return True
-    message = str(err).lower()
-    return any(marker in message for marker in _CALENDAR_EVENT_ABSENT_MARKERS)
-
-
-async def _recreate_calendar_event(
-    client: Any,
-    cal: str,
-    event: dict[str, Any],
-    start: tuple[str, bool],
-    end: tuple[str, bool],
-) -> Any:
-    """Create an event that no longer exists under its snapshotted uid.
-
-    Always a single event: a series-wide write is never snapshotted (the
-    calendar view cannot describe the series), and a snapshot of one
-    occurrence must not be re-created as a series of its own.
-    """
-    data: dict[str, Any] = {"entity_id": cal, "summary": event["summary"]}
-    if start[1]:
-        data.update({"start_date": start[0], "end_date": end[0]})
-    else:
-        data.update({"start_date_time": start[0], "end_date_time": end[0]})
-    for key in ("description", "location"):
-        if event.get(key):
-            data[key] = event[key]
-    return await _rest_post(client, "services/calendar/create_event", data)
-
-
-async def _restore_calendar_event(client: Any, entity_id: str, config: Any) -> Any:
-    cal, _, rest = entity_id.partition("::")
-    key_uid, _, key_recurrence_id = rest.partition("::")
-    cal = config.get("calendar_entity_id") or cal
-    uid = config.get("uid") or key_uid
-    recurrence_id = config.get("recurrence_id") or key_recurrence_id or None
-    start = _calendar_bound(config.get("start"))
-    end = _calendar_bound(config.get("end"))
-    if start is None or end is None:
-        raise HomeAssistantError(
-            f"Calendar snapshot for {entity_id!r} has no usable start/end"
-        )
-
-    # Home Assistant merges the update into the stored event (ical dumps it
-    # with ``exclude_unset``), so a field left out keeps whatever the write
-    # put there. Send the text fields unconditionally — empty clears a
-    # description or location the write added.
-    event: dict[str, Any] = {
-        "summary": config.get("summary") or "",
-        "dtstart": start[0],
-        "dtend": end[0],
-        "description": config.get("description") or "",
-        "location": config.get("location") or "",
-    }
-    # ``rrule`` is deliberately never replayed. Every expanded occurrence
-    # carries the series' rule, and sending it back onto one occurrence —
-    # which ical has already forked into a plain event — would make that
-    # occurrence a second series under the same uid, duplicating every later
-    # date.
-
-    if not uid:
-        return await _recreate_calendar_event(client, cal, event, start, end)
-
-    # An edited event still exists under its uid, so put the captured values
-    # back in place instead of creating a second copy. Only a snapshot of a
-    # DELETED event (or a calendar without UPDATE_EVENT) falls through to
-    # re-creation.
-    message: dict[str, Any] = {
-        "type": "calendar/event/update",
-        "entity_id": cal,
-        "uid": uid,
-        "event": event,
-    }
-    if recurrence_id:
-        message["recurrence_id"] = recurrence_id
-    try:
-        return await _ws_send(client, message)
-    except HomeAssistantCommandError as err:
-        if not _calendar_update_cannot_apply(err):
-            # A transport drop, a timeout or an unclassified command failure
-            # leaves it unknown whether HA applied the update; re-creating
-            # then leaves a duplicate behind. Only a failure that PROVES the
-            # update never landed falls through. Connection errors and
-            # timeouts are separate types, so they never reach here at all.
-            raise
-        if recurrence_id:
-            # The occurrence is gone — deleted from the series, or the series
-            # moved and this recurrence_id no longer names one of its dates.
-            # ``create_event`` could only add a detached event next to the
-            # series, which is not the occurrence being restored, so say so
-            # instead of inventing one.
-            raise HomeAssistantError(
-                f"Occurrence {recurrence_id} of event {uid} no longer exists on "
-                f"{cal}, and an occurrence cannot be re-created into its series"
-            ) from err
-        logger.info(
-            "Restoring calendar event %s on %s in place is not possible (%s); "
-            "re-creating it instead",
-            uid,
-            cal,
-            err,
-        )
-    return await _recreate_calendar_event(client, cal, event, start, end)
-
-
 # Areas / floors — config/area_registry/{list,update}, config/floor_registry/{list,update}