Add calendar platform to Habitica integration

homeassistant/components/habitica/__init__.py

@@ -57,7 +57,13 @@
 type HabiticaConfigEntry = ConfigEntry[HabiticaDataUpdateCoordinator]
 
 
-PLATFORMS = [Platform.BUTTON, Platform.SENSOR, Platform.SWITCH, Platform.TODO]
+PLATFORMS = [
+    Platform.BUTTON,
+    Platform.CALENDAR,
+    Platform.SENSOR,
+    Platform.SWITCH,
+    Platform.TODO,
+]
 
 
 SERVICE_API_CALL_SCHEMA = vol.Schema(

homeassistant/components/habitica/calendar.py

@@ -0,0 +1,197 @@
+"""Calendar platform for Habitica integration."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta
+from enum import StrEnum
+
+from homeassistant.components.calendar import (
+    CalendarEntity,
+    CalendarEntityDescription,
+    CalendarEvent,
+)
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from homeassistant.util import dt as dt_util
+
+from . import HabiticaConfigEntry
+from .coordinator import HabiticaDataUpdateCoordinator
+from .entity import HabiticaBase
+from .types import HabiticaTaskType
+from .util import build_rrule, get_recurrence_rule, to_date
+
+
+class HabiticaCalendar(StrEnum):
+    """Habitica calendars."""
+
+    DAILIES = "dailys"
+    TODOS = "todos"
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    config_entry: HabiticaConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up the calendar platform."""
+    coordinator = config_entry.runtime_data
+
+    async_add_entities(
+        [
+            HabiticaTodosCalendarEntity(coordinator),
+            HabiticaDailiesCalendarEntity(coordinator),
+        ]
+    )
+
+
+class HabiticaCalendarEntity(HabiticaBase, CalendarEntity):
+    """Base Habitica calendar entity."""
+
+    def __init__(
+        self,
+        coordinator: HabiticaDataUpdateCoordinator,
+    ) -> None:
+        """Initialize calendar entity."""
+        super().__init__(coordinator, self.entity_description)
+
+
+class HabiticaTodosCalendarEntity(HabiticaCalendarEntity):
+    """Habitica todos calendar entity."""
+
+    entity_description = CalendarEntityDescription(
+        key=HabiticaCalendar.TODOS,
+        translation_key=HabiticaCalendar.TODOS,
+    )
+
+    @property
+    def event(self) -> CalendarEvent | None:
+        """Return the next upcoming event."""
+
+        events = [
+            CalendarEvent(
+                start=start,
+                end=start + timedelta(days=1),
+                summary=task["text"],
+                description=task["notes"],
+                uid=task["id"],
+            )
+            for task in self.coordinator.data.tasks
+            if task["type"] == HabiticaTaskType.TODO
+            and not task["completed"]
+            and task.get("date")
+            and (start := to_date(task["date"]))
+            and start >= dt_util.now().date()
+        ]
+        events_sorted = sorted(
+            events,
+            key=lambda event: (
+                event.start,
+                self.coordinator.data.user["tasksOrder"]["todos"].index(event.uid),
+            ),
+        )
+
+        return events_sorted[0] if events_sorted else None
+
+    async def async_get_events(
+        self, hass: HomeAssistant, start_date: datetime, end_date: datetime
+    ) -> list[CalendarEvent]:
+        """Return calendar events within a datetime range."""
+
+        return [
+            CalendarEvent(
+                start=start,
+                end=start + timedelta(days=1),
+                summary=task["text"],
+                description=task["notes"],
+                uid=task["id"],
+            )
+            for task in self.coordinator.data.tasks
+            if task["type"] == HabiticaTaskType.TODO
+            and not task["completed"]
+            and task.get("date")
+            and (start := to_date(task["date"]))
+            and (start_date.date() <= start <= end_date.date())
+        ]
+
+
+class HabiticaDailiesCalendarEntity(HabiticaCalendarEntity):
+    """Habitica dailies calendar entity."""
+
+    entity_description = CalendarEntityDescription(
+        key=HabiticaCalendar.DAILIES,
+        translation_key=HabiticaCalendar.DAILIES,
+    )
+
+    @property
+    def today(self) -> datetime:
+        """Habitica daystart."""
+        return datetime.fromisoformat(self.coordinator.data.user["lastCron"])
+
+    def calculate_end_date(self, next_recurrence) -> date:
+        """Calculate the end date for a yesterdaily."""
+        return (
+            dt_util.start_of_local_day()
+            if next_recurrence == self.today
+            else next_recurrence
+        ).date() + timedelta(days=1)
+
+    @property
+    def event(self) -> CalendarEvent | None:
+        """Return the next upcoming event."""
+
+        events = [
+            CalendarEvent(
+                start=next_recurrence.date(),
+                end=self.calculate_end_date(next_recurrence),
+                summary=task["text"],
+                description=task["notes"],
+                uid=task["id"],
+            )
+            for task in self.coordinator.data.tasks
+            if task["type"] == HabiticaTaskType.DAILY and task["everyX"]
+            if (
+                next_recurrence := self.today
+                if not task["completed"] and task["isDue"]
+                else build_rrule(task).after(self.today, inc=True)
+            )
+        ]
+        events_sorted = sorted(
+            events,
+            key=lambda event: (
+                event.start,
+                self.coordinator.data.user["tasksOrder"]["dailys"].index(event.uid),
+            ),
+        )
+
+        return events_sorted[0] if events_sorted else None
+
+    async def async_get_events(
+        self, hass: HomeAssistant, start_date: datetime, end_date: datetime
+    ) -> list[CalendarEvent]:
+        """Return calendar events within a datetime range."""
+
+        # returns only todays and future dailies.
+        # If a daily is completed it will not be shown for today but still future recurrences
+        # If the cron hasn't run, not completed dailies are yesterdailies and displayed yesterday
+        return [
+            CalendarEvent(
+                start=start,
+                end=start + timedelta(days=1),
+                summary=task["text"],
+                description=task["notes"],
+                uid=task["id"],
+                rrule=get_recurrence_rule(task),
+            )
+            for task in self.coordinator.data.tasks
+            if task["type"] == HabiticaTaskType.DAILY and task["everyX"]
+            for recurrence in build_rrule(task).between(start_date, end_date, inc=True)
+            if (start := recurrence.date()) > self.today.date()
+            or (start == self.today.date() and not task["completed"] and task["isDue"])
+        ]
+
+    @property
+    def extra_state_attributes(self) -> dict[str, bool] | None:
+        """Return entity specific state attributes."""
+        if event := self.event:
+            return {"yesterdaily": event.start < date.today()}
+        return None

homeassistant/components/habitica/icons.json

@@ -22,6 +22,14 @@
         "default": "mdi:grave-stone"
       }
     },
+    "calendar": {
+      "todos": {
+        "default": "mdi:calendar-check"
+      },
+      "dailys": {
+        "default": "mdi:calendar-multiple"
+      }
+    },
     "sensor": {
       "display_name": {
         "default": "mdi:account-circle"

homeassistant/components/habitica/strings.json

@@ -48,6 +48,23 @@
         "name": "Revive from death"
       }
     },
+    "calendar": {
+      "todos": {
+        "name": "To-Do's"
+      },
+      "dailys": {
+        "name": "Dailies",
+        "state_attributes": {
+          "yesterdaily": {
+            "name": "Yester-Daily",
+            "state": {
+              "true": "[%key:common::state::yes%]",
+              "false": "[%key:common::state::no%]"
+            }
+          }
+        }
+      }
+    },
     "sensor": {
       "display_name": {
         "name": "Display name"

homeassistant/components/habitica/todo.py

@@ -25,6 +25,7 @@
 from .const import ASSETS_URL, DOMAIN
 from .coordinator import HabiticaDataUpdateCoordinator
 from .entity import HabiticaBase
+from .types import HabiticaTaskType
 from .util import next_due_date
 
 
@@ -37,15 +38,6 @@ class HabiticaTodoList(StrEnum):
     REWARDS = "rewards"
 
 
-class HabiticaTaskType(StrEnum):
-    """Habitica Entities."""
-
-    HABIT = "habit"
-    DAILY = "daily"
-    TODO = "todo"
-    REWARD = "reward"
-
-
 async def async_setup_entry(
     hass: HomeAssistant,
     config_entry: HabiticaConfigEntry,

homeassistant/components/habitica/types.py

@@ -0,0 +1,12 @@
+"""Types for Habitica integration."""
+
+from enum import StrEnum
+
+
+class HabiticaTaskType(StrEnum):
+    """Habitica Entities."""
+
+    HABIT = "habit"
+    DAILY = "daily"
+    TODO = "todo"
+    REWARD = "reward"

homeassistant/components/habitica/util.py

@@ -5,6 +5,21 @@
 import datetime
 from typing import TYPE_CHECKING, Any
 
+from dateutil.rrule import (
+    DAILY,
+    FR,
+    MO,
+    MONTHLY,
+    SA,
+    SU,
+    TH,
+    TU,
+    WE,
+    WEEKLY,
+    YEARLY,
+    rrule,
+)
+
 from homeassistant.components.automation import automations_with_entity
 from homeassistant.components.script import scripts_with_entity
 from homeassistant.core import HomeAssistant
@@ -62,3 +77,65 @@
     used_in = automations_with_entity(hass, entity_id)
     used_in += scripts_with_entity(hass, entity_id)
     return used_in
+
+
+frequency_map = {"daily": DAILY, "weekly": WEEKLY, "monthly": MONTHLY, "yearly": YEARLY}
+weekday_map = {"m": MO, "t": TU, "w": WE, "th": TH, "f": FR, "s": SA, "su": SU}
+
+
+def build_rrule(task: dict[str, Any]) -> rrule:
+    """Build rrule string."""
+
+    rrule_frequency = frequency_map.get(task["frequency"], DAILY)
+    weekdays = [
+        weekday_map[day] for day, is_active in task["repeat"].items() if is_active
+    ]
+    bymonthday = (
+        task["daysOfMonth"]
+        if rrule_frequency == MONTHLY and task["daysOfMonth"]
+        else None
+    )
+
+    bysetpos = None
+    if rrule_frequency == MONTHLY and task["weeksOfMonth"]:
+        bysetpos = task["weeksOfMonth"]
+        weekdays = weekdays if weekdays else [MO]
+
+    return rrule(
+        freq=rrule_frequency,
+        interval=task["everyX"],
+        dtstart=dt_util.as_local(datetime.datetime.fromisoformat(task["startDate"])),
+        byweekday=weekdays if rrule_frequency in [WEEKLY, MONTHLY] else None,
+        bymonthday=bymonthday,
+        bysetpos=bysetpos,
+    )
+
+
+def get_recurrence_rule(task: dict[str, Any]) -> str:
+    r"""Return the recurrence rules of an RRULE object from a task.
+
+    This function takes a task dictionary, builds the RRULE string using
+    the `build_rrule` function, and returns the recurrence rule part. The
+    string representation of the RRULE has the following format:
+
+    'DTSTART:YYYYMMDDTHHMMSS\nRRULE:FREQ=YEARLY;INTERVAL=2'
+
+    Parameters
+    ----------
+    task : dict of {str : Any}
+        A dictionary containing task details.
+
+    Returns
+    -------
+    str
+        The recurrence rule portion of the RRULE string, starting with 'FREQ='.
+
+    Example
+    -------
+    >>> rule = get_recurrence_rule(task)
+    >>> print(rule)
+    'FREQ=YEARLY;INTERVAL=2'
+
+    """
+    recurrence = build_rrule(task)
+    return str(recurrence).split("RRULE:")[1]

tests/components/habitica/fixtures/tasks.json

@@ -444,7 +444,12 @@
         "completedBy": {},
         "assignedUsers": []
       },
-      "reminders": [],
+      "reminders": [
+        {
+          "id": "91c09432-10ac-4a49-bd20-823081ec29ed",
+          "time": "2024-09-22T02:00:00.0000Z"
+        }
+      ],
       "byHabitica": false,
       "createdAt": "2024-09-21T22:17:19.513Z",
       "updatedAt": "2024-09-21T22:19:35.576Z",
@@ -477,7 +482,7 @@
     },
     {
       "_id": "86ea2475-d1b5-4020-bdcc-c188c7996afa",
-      "date": "2024-09-26T22:15:00.000Z",
+      "date": "2024-09-21T22:00:00.000Z",
       "completed": false,
       "collapseChecklist": false,
       "checklist": [],