feat(jmap): add caldav/jmap — JMAP calendar and task client

CHANGELOG.md

@@ -189,6 +189,19 @@ Additionally, direct `DAVClient()` instantiation should migrate to `get_davclien
 
 ### Added
 
+* **JMAP calendar client** — new `caldav.jmap` package providing a JMAP client
+  for servers implementing RFC 8620 (JMAP Core) and RFC 8984 (JMAP Calendars).
+  Features:
+  - Synchronous `JMAPClient` and asynchronous `AsyncJMAPClient` with mirrored APIs
+  - Full calendar + event CRUD (`create_event`, `get_event`, `update_event`,
+    `delete_event`, `search_events`)
+  - Incremental sync via `get_sync_token` / `get_objects_by_sync_token`
+  - Task CRUD (draft-ietf-jmap-tasks) via `create_task`, `get_task`, `update_task`, `delete_task`
+  - Bidirectional iCalendar ↔ JSCalendar conversion layer
+  - `get_jmap_client()` factory reads from the same config sources as
+    `get_davclient()` (env vars, config file)
+  - Tested against Cyrus IMAP
+
 * **Full async API** - New `AsyncDAVClient` and async-compatible domain objects:
   ```python
   from caldav.async_davclient import get_davclient

caldav/base_client.py

@@ -592,6 +592,9 @@ def get_davclient(
     setup_func = conn_params.pop("_setup", None)
     teardown_func = conn_params.pop("_teardown", None)
     server_name = conn_params.pop("_server_name", None)
+    # Remove protocol field — present when config file has both CalDAV and JMAP sections,
+    # or when the caller passes protocol="jmap"/"caldav". DAVClient doesn't accept it.
+    conn_params.pop("protocol", None)
 
     # Create client
     client = client_class(**conn_params)

caldav/config.py

@@ -206,6 +206,7 @@ def resolve_features(features):
         "features",
         "enable_rfc6764",
         "require_tls",
+        "protocol",
     ]
 )
 

caldav/jmap/__init__.py

@@ -0,0 +1,102 @@
+"""
+JMAP calendar support for python-caldav.
+
+Provides synchronous and asynchronous JMAP clients with the same public API as
+the CalDAV client, so user code works regardless of server protocol.
+
+Basic usage::
+
+    from caldav.jmap import get_jmap_client
+
+    client = get_jmap_client(
+        url="https://jmap.example.com/.well-known/jmap",
+        username="alice",
+        password="secret",
+    )
+    calendars = client.get_calendars()
+
+Async usage::
+
+    from caldav.jmap import get_async_jmap_client
+
+    async with get_async_jmap_client(
+        url="https://jmap.example.com/.well-known/jmap",
+        username="alice",
+        password="secret",
+    ) as client:
+        calendars = await client.get_calendars()
+"""
+
+from caldav.jmap.async_client import AsyncJMAPClient
+from caldav.jmap.client import JMAPClient
+from caldav.jmap.error import (
+    JMAPAuthError,
+    JMAPCapabilityError,
+    JMAPError,
+    JMAPMethodError,
+)
+from caldav.jmap.objects.calendar import JMAPCalendar
+from caldav.jmap.objects.calendar_object import JMAPCalendarObject
+
+_JMAP_KEYS = {"url", "username", "password", "auth", "auth_type", "timeout"}
+
+
+def get_jmap_client(**kwargs) -> JMAPClient | None:
+    """Create a :class:`JMAPClient` from configuration.
+
+    Configuration is read from the same sources as :func:`caldav.get_davclient`:
+
+    1. Explicit keyword arguments (``url``, ``username``, ``password``, …)
+    2. Environment variables (``CALDAV_URL``, ``CALDAV_USERNAME``, …)
+    3. Config file (``~/.config/caldav/calendar.conf`` or equivalent)
+
+    Returns ``None`` if no configuration is found, matching the behaviour
+    of :func:`caldav.get_davclient`.
+
+    Example::
+
+        client = get_jmap_client(url="https://jmap.example.com/.well-known/jmap",
+                                  username="alice", password="secret")
+    """
+    from caldav.config import get_connection_params
+
+    conn_params = get_connection_params(**kwargs)
+    if conn_params is None:
+        return None
+    return JMAPClient(**{k: v for k, v in conn_params.items() if k in _JMAP_KEYS})
+
+
+def get_async_jmap_client(**kwargs) -> AsyncJMAPClient | None:
+    """Create an :class:`AsyncJMAPClient` from configuration.
+
+    Accepts the same arguments and reads configuration from the same sources
+    as :func:`get_jmap_client`. Returns ``None`` if no configuration is found.
+
+    Example::
+
+        async with get_async_jmap_client(
+            url="https://jmap.example.com/.well-known/jmap",
+            username="alice", password="secret"
+        ) as client:
+            calendars = await client.get_calendars()
+    """
+    from caldav.config import get_connection_params
+
+    conn_params = get_connection_params(**kwargs)
+    if conn_params is None:
+        return None
+    return AsyncJMAPClient(**{k: v for k, v in conn_params.items() if k in _JMAP_KEYS})
+
+
+__all__ = [
+    "JMAPClient",
+    "AsyncJMAPClient",
+    "get_jmap_client",
+    "get_async_jmap_client",
+    "JMAPError",
+    "JMAPCapabilityError",
+    "JMAPAuthError",
+    "JMAPMethodError",
+    "JMAPCalendar",
+    "JMAPCalendarObject",
+]

caldav/jmap/_methods/__init__.py

@@ -0,0 +1,12 @@
+def parse_set_response(response_args: dict) -> tuple[dict, dict, list[str], dict, dict, dict]:
+    """Parse the arguments dict from any JMAP ``*/set`` method response.
+
+    Returns a 6-tuple ``(created, updated, destroyed, not_created, not_updated, not_destroyed)``.
+    """
+    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

caldav/jmap/_methods/calendar.py

@@ -0,0 +1,68 @@
+"""
+JMAP Calendar 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.4 (changes), §3.5 (set); Calendar-specific
+properties are defined in the JMAP Calendars specification.
+"""
+
+from __future__ import annotations
+
+from caldav.jmap.objects.calendar import JMAPCalendar
+
+
+def build_calendar_get(
+    account_id: str,
+    ids: list[str] | None = None,
+    properties: list[str] | None = None,
+) -> tuple:
+    """Build a ``Calendar/get`` method call tuple.
+
+    Args:
+        account_id: The JMAP accountId to query.
+        ids: List of calendar IDs to fetch, or ``None`` to fetch all.
+        properties: List of property names to return, or ``None`` for all.
+
+    Returns:
+        A 3-tuple ``("Calendar/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 ("Calendar/get", args, "cal-get-0")
+
+
+def parse_calendar_get(response_args: dict) -> list[JMAPCalendar]:
+    """Parse the arguments dict from a ``Calendar/get`` method response.
+
+    Args:
+        response_args: The second element of a ``methodResponses`` entry
+            whose method name is ``"Calendar/get"``.
+
+    Returns:
+        List of :class:`~caldav.jmap.objects.calendar.JMAPCalendar` objects.
+        Returns an empty list if ``"list"`` is absent or empty.
+    """
+    return [JMAPCalendar.from_jmap(item) for item in response_args.get("list", [])]
+
+
+def build_calendar_changes(account_id: str, since_state: str) -> tuple:
+    """Build a ``Calendar/changes`` method call tuple.
+
+    Args:
+        account_id: The JMAP accountId to query.
+        since_state: The ``state`` string from a previous ``Calendar/get``
+            or ``Calendar/changes`` response.
+
+    Returns:
+        A 3-tuple ``("Calendar/changes", arguments_dict, call_id)``.
+    """
+    return (
+        "Calendar/changes",
+        {"accountId": account_id, "sinceState": since_state},
+        "cal-changes-0",
+    )