feat(jmap): add Task and TaskList support via RFC 9553

Author: SashankBhamidi

caldav/jmap/client.py

@@ -11,6 +11,7 @@
 from __future__ import annotations
 
 import logging
+import uuid
 
 try:
     import niquests as requests
@@ -19,7 +20,7 @@
     import requests  # type: ignore[no-redef]
     from requests.auth import HTTPBasicAuth  # type: ignore[no-redef]
 
-from caldav.jmap.constants import CALENDAR_CAPABILITY, CORE_CAPABILITY
+from caldav.jmap.constants import CALENDAR_CAPABILITY, CORE_CAPABILITY, TASK_CAPABILITY
 from caldav.jmap.convert import ical_to_jscal, jscal_to_ical
 from caldav.jmap.error import JMAPAuthError, JMAPMethodError
 from caldav.jmap.methods.calendar import build_calendar_get, parse_calendar_get
@@ -32,13 +33,24 @@
     parse_event_changes,
     parse_event_set,
 )
+from caldav.jmap.methods.task import (
+    build_task_get,
+    build_task_list_get,
+    build_task_set_create,
+    build_task_set_destroy,
+    build_task_set_update,
+    parse_task_list_get,
+    parse_task_set,
+)
 from caldav.jmap.objects.calendar import JMAPCalendar
+from caldav.jmap.objects.task import JMAPTask, JMAPTaskList
 from caldav.jmap.session import Session, fetch_session
 from caldav.requests import HTTPBearerAuth
 
 log = logging.getLogger("caldav.jmap")
 
 _DEFAULT_USING = [CORE_CAPABILITY, CALENDAR_CAPABILITY]
+_TASK_USING = [CORE_CAPABILITY, TASK_CAPABILITY]
 
 
 class JMAPClient:
@@ -130,7 +142,7 @@ def _build_auth(self, auth_type: str | None):
     def _raise_set_error(self, session: Session, err: dict) -> None:
         raise JMAPMethodError(
             url=session.api_url,
-            reason=f"CalendarEvent/set failed: {err}",
+            reason=f"set failed: {err}",
             error_type=err.get("type", "serverError"),
         )
 
@@ -140,11 +152,13 @@ def _get_session(self) -> Session:
             self._session_cache = fetch_session(self.url, auth=self._auth, timeout=self.timeout)
         return self._session_cache
 
-    def _request(self, method_calls: list[tuple]) -> list:
+    def _request(self, method_calls: list[tuple], using: list[str] | None = None) -> list:
         """POST a batch of JMAP method calls and return the methodResponses.
 
         Args:
             method_calls: List of 3-tuples ``(method_name, args_dict, call_id)``.
+            using: Capability URN list for the ``using`` field. Defaults to
+                ``_DEFAULT_USING`` (core + calendars).
 
         Returns:
             List of 3-tuples ``(method_name, response_args, call_id)`` from
@@ -158,7 +172,7 @@ def _request(self, method_calls: list[tuple]) -> list:
         session = self._get_session()
 
         payload = {
-            "using": _DEFAULT_USING,
+            "using": using if using is not None else _DEFAULT_USING,
             "methodCalls": list(method_calls),
         }
 
@@ -450,3 +464,129 @@ def delete_event(self, event_id: str) -> None:
                 return
 
         raise JMAPMethodError(url=session.api_url, reason="No CalendarEvent/set response")
+
+    def get_task_lists(self) -> list[JMAPTaskList]:
+        """Fetch all task lists for the authenticated account.
+
+        Returns:
+            List of :class:`~caldav.jmap.objects.task.JMAPTaskList` objects.
+        """
+        session = self._get_session()
+        call = build_task_list_get(session.account_id)
+        responses = self._request([call], using=_TASK_USING)
+
+        for method_name, resp_args, _ in responses:
+            if method_name == "TaskList/get":
+                return parse_task_list_get(resp_args)
+
+        return []
+
+    def create_task(self, task_list_id: str, title: str, **kwargs) -> str:
+        """Create a task in a task list.
+
+        Args:
+            task_list_id: The JMAP task list ID to create the task in.
+            title: Task title (maps to VTODO ``SUMMARY``).
+            **kwargs: Optional task fields: ``description``, ``due``, ``start``,
+                ``time_zone``, ``estimated_duration``, ``percent_complete``,
+                ``progress``, ``priority``.
+
+        Returns:
+            The server-assigned JMAP task ID.
+
+        Raises:
+            JMAPMethodError: If the server rejects the create request.
+        """
+        session = self._get_session()
+        task = JMAPTask(
+            id="",
+            uid=str(uuid.uuid4()),
+            task_list_id=task_list_id,
+            title=title,
+            **kwargs,
+        )
+        call = build_task_set_create(session.account_id, {"new-0": task})
+        responses = self._request([call], using=_TASK_USING)
+
+        for method_name, resp_args, _ in responses:
+            if method_name == "Task/set":
+                created, _, _, not_created, _, _ = parse_task_set(resp_args)
+                if "new-0" in not_created:
+                    self._raise_set_error(session, not_created["new-0"])
+                return created["new-0"]["id"]
+
+        raise JMAPMethodError(url=session.api_url, reason="No Task/set response")
+
+    def get_task(self, task_id: str) -> JMAPTask:
+        """Fetch a task by ID.
+
+        Args:
+            task_id: The JMAP task ID to retrieve.
+
+        Returns:
+            A :class:`~caldav.jmap.objects.task.JMAPTask` object.
+
+        Raises:
+            JMAPMethodError: If the task is not found.
+        """
+        session = self._get_session()
+        call = build_task_get(session.account_id, ids=[task_id])
+        responses = self._request([call], using=_TASK_USING)
+
+        for method_name, resp_args, _ in responses:
+            if method_name == "Task/get":
+                items = resp_args.get("list", [])
+                if not items:
+                    raise JMAPMethodError(
+                        url=session.api_url,
+                        reason=f"Task not found: {task_id}",
+                        error_type="notFound",
+                    )
+                return JMAPTask.from_jmap(items[0])
+
+        raise JMAPMethodError(url=session.api_url, reason="No Task/get response")
+
+    def update_task(self, task_id: str, patch: dict) -> None:
+        """Update a task with a partial patch.
+
+        Args:
+            task_id: The JMAP task ID to update.
+            patch: Partial patch dict mapping property names to new values.
+
+        Raises:
+            JMAPMethodError: If the server rejects the update.
+        """
+        session = self._get_session()
+        call = build_task_set_update(session.account_id, {task_id: patch})
+        responses = self._request([call], using=_TASK_USING)
+
+        for method_name, resp_args, _ in responses:
+            if method_name == "Task/set":
+                _, _, _, _, not_updated, _ = parse_task_set(resp_args)
+                if task_id in not_updated:
+                    self._raise_set_error(session, not_updated[task_id])
+                return
+
+        raise JMAPMethodError(url=session.api_url, reason="No Task/set response")
+
+    def delete_task(self, task_id: str) -> None:
+        """Delete a task.
+
+        Args:
+            task_id: The JMAP task ID to delete.
+
+        Raises:
+            JMAPMethodError: If the server rejects the delete.
+        """
+        session = self._get_session()
+        call = build_task_set_destroy(session.account_id, [task_id])
+        responses = self._request([call], using=_TASK_USING)
+
+        for method_name, resp_args, _ in responses:
+            if method_name == "Task/set":
+                _, _, _, _, _, not_destroyed = parse_task_set(resp_args)
+                if task_id in not_destroyed:
+                    self._raise_set_error(session, not_destroyed[task_id])
+                return
+
+        raise JMAPMethodError(url=session.api_url, reason="No Task/set response")

caldav/jmap/methods/task.py

@@ -0,0 +1,176 @@
+"""
+JMAP Task and TaskList method builders and response parsers.
+
+These are pure functions — no HTTP, no state. They build the request
+tuples that go into a ``methodCalls`` list, and parse the corresponding
+``methodResponses`` entries.
+
+Method shapes follow RFC 8620 §3.3 (get), §3.5 (set); Task-specific
+properties are defined in RFC 9553 (JMAP for Tasks).
+"""
+
+from __future__ import annotations
+
+from caldav.jmap.objects.task import JMAPTask, JMAPTaskList
+
+
+def build_task_list_get(
+    account_id: str,
+    ids: list[str] | None = None,
+    properties: list[str] | None = None,
+) -> tuple:
+    """Build a ``TaskList/get`` method call tuple.
+
+    Args:
+        account_id: The JMAP accountId to query.
+        ids: List of task list IDs to fetch, or ``None`` to fetch all.
+        properties: List of property names to return, or ``None`` for all.
+
+    Returns:
+        A 3-tuple ``("TaskList/get", arguments_dict, call_id)`` suitable
+        for inclusion in a ``methodCalls`` list.
+    """
+    args: dict = {"accountId": account_id, "ids": ids}
+    if properties is not None:
+        args["properties"] = properties
+    return ("TaskList/get", args, "tasklist-get-0")
+
+
+def parse_task_list_get(response_args: dict) -> list[JMAPTaskList]:
+    """Parse the arguments dict from a ``TaskList/get`` method response.
+
+    Args:
+        response_args: The second element of a ``methodResponses`` entry
+            whose method name is ``"TaskList/get"``.
+
+    Returns:
+        List of :class:`~caldav.jmap.objects.task.JMAPTaskList` objects.
+        Returns an empty list if ``"list"`` is absent or empty.
+    """
+    return [JMAPTaskList.from_jmap(item) for item in response_args.get("list", [])]
+
+
+def build_task_get(
+    account_id: str,
+    ids: list[str] | None = None,
+    properties: list[str] | None = None,
+) -> tuple:
+    """Build a ``Task/get`` method call tuple.
+
+    Args:
+        account_id: The JMAP accountId to query.
+        ids: List of task IDs to fetch, or ``None`` to fetch all.
+        properties: List of property names to return, or ``None`` for all.
+
+    Returns:
+        A 3-tuple ``("Task/get", arguments_dict, call_id)``.
+    """
+    args: dict = {"accountId": account_id, "ids": ids}
+    if properties is not None:
+        args["properties"] = properties
+    return ("Task/get", args, "task-get-0")
+
+
+def parse_task_get(response_args: dict) -> list[JMAPTask]:
+    """Parse the arguments dict from a ``Task/get`` method response.
+
+    Args:
+        response_args: The second element of a ``methodResponses`` entry
+            whose method name is ``"Task/get"``.
+
+    Returns:
+        List of :class:`~caldav.jmap.objects.task.JMAPTask` objects.
+        Returns an empty list if ``"list"`` is absent or empty.
+    """
+    return [JMAPTask.from_jmap(item) for item in response_args.get("list", [])]
+
+
+def build_task_set_create(
+    account_id: str,
+    tasks: dict[str, JMAPTask],
+) -> tuple:
+    """Build a ``Task/set`` method call for creating tasks.
+
+    Args:
+        account_id: The JMAP accountId.
+        tasks: Map of client-assigned creation ID → :class:`JMAPTask`.
+
+    Returns:
+        A 3-tuple ``("Task/set", arguments_dict, call_id)``.
+    """
+    return (
+        "Task/set",
+        {
+            "accountId": account_id,
+            "create": {cid: task.to_jmap() for cid, task in tasks.items()},
+        },
+        "task-set-create-0",
+    )
+
+
+def build_task_set_update(
+    account_id: str,
+    updates: dict[str, dict],
+) -> tuple:
+    """Build a ``Task/set`` method call for updating tasks.
+
+    Args:
+        account_id: The JMAP accountId.
+        updates: Map of task ID → partial patch dict.
+
+    Returns:
+        A 3-tuple ``("Task/set", arguments_dict, call_id)``.
+    """
+    return (
+        "Task/set",
+        {"accountId": account_id, "update": updates},
+        "task-set-update-0",
+    )
+
+
+def build_task_set_destroy(
+    account_id: str,
+    ids: list[str],
+) -> tuple:
+    """Build a ``Task/set`` method call for destroying tasks.
+
+    Args:
+        account_id: The JMAP accountId.
+        ids: List of task IDs to destroy.
+
+    Returns:
+        A 3-tuple ``("Task/set", arguments_dict, call_id)``.
+    """
+    return (
+        "Task/set",
+        {"accountId": account_id, "destroy": ids},
+        "task-set-destroy-0",
+    )
+
+
+def parse_task_set(
+    response_args: dict,
+) -> tuple[dict, dict, list[str], dict, dict, dict]:
+    """Parse the arguments dict from a ``Task/set`` method response.
+
+    Args:
+        response_args: The second element of a ``methodResponses`` entry
+            whose method name is ``"Task/set"``.
+
+    Returns:
+        A 6-tuple ``(created, updated, destroyed, not_created, not_updated, not_destroyed)``:
+
+        - ``created``: Map of creation ID → server-assigned task dict.
+        - ``updated``: Map of task ID → null or partial server-updated object.
+        - ``destroyed``: List of successfully destroyed task IDs.
+        - ``not_created``: Map of creation ID → SetError dict for failed creates.
+        - ``not_updated``: Map of task ID → SetError dict for failed updates.
+        - ``not_destroyed``: Map of task ID → SetError dict for failed destroys.
+    """
+    created: dict = response_args.get("created") or {}
+    updated: dict = response_args.get("updated") or {}
+    destroyed: list[str] = response_args.get("destroyed") or []
+    not_created: dict = response_args.get("notCreated") or {}
+    not_updated: dict = response_args.get("notUpdated") or {}
+    not_destroyed: dict = response_args.get("notDestroyed") or {}
+    return created, updated, destroyed, not_created, not_updated, not_destroyed