Skip to content

Personal AI, On Personal Devices

Python

feat: add Google Calendar connector with event sync

krypticmouse79616c9da4d9
diff --git a/src/openjarvis/connectors/gcalendar.py b/src/openjarvis/connectors/gcalendar.py
new file mode 100644
index 00000000..54d4e36d
--- /dev/null
+++ b/src/openjarvis/connectors/gcalendar.py
@@ -0,0 +1,421 @@
+"""Google Calendar connector — event sync via the Calendar REST API v3.
+
+Uses OAuth 2.0 tokens stored locally (see :mod:`openjarvis.connectors.oauth`).
+All network calls are isolated in module-level functions (``_gcal_api_*``)
+to make them trivially mockable in tests.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, Iterator, List, Optional
+
+import httpx
+
+from openjarvis.connectors._stubs import BaseConnector, Document, SyncStatus
+from openjarvis.connectors.oauth import (
+ build_google_auth_url,
+ delete_tokens,
+ load_tokens,
+ save_tokens,
+)
+from openjarvis.core.config import DEFAULT_CONFIG_DIR
+from openjarvis.core.registry import ConnectorRegistry
+from openjarvis.tools._stubs import ToolSpec
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_GCAL_API_BASE = "https://www.googleapis.com/calendar/v3"
+_GCAL_SCOPE = "https://www.googleapis.com/auth/calendar.readonly"
+_DEFAULT_CREDENTIALS_PATH = str(DEFAULT_CONFIG_DIR / "connectors" / "gcalendar.json")
+
+# ---------------------------------------------------------------------------
+# Module-level API functions (easy to patch in tests)
+# ---------------------------------------------------------------------------
+
+
+def _gcal_api_calendars_list(token: str) -> Dict[str, Any]:
+ """Call the Calendar ``calendarList.list`` endpoint.
+
+ Parameters
+ ----------
+ token:
+ OAuth access token.
+
+ Returns
+ -------
+ dict
+ Raw API response containing an ``items`` list of calendar resources.
+ """
+ resp = httpx.get(
+ f"{_GCAL_API_BASE}/users/me/calendarList",
+ headers={"Authorization": f"Bearer {token}"},
+ timeout=30.0,
+ )
+ resp.raise_for_status()
+ return resp.json()
+
+
+def _gcal_api_events_list(
+ token: str,
+ calendar_id: str,
+ *,
+ page_token: Optional[str] = None,
+ time_min: Optional[str] = None,
+) -> Dict[str, Any]:
+ """Call the Calendar ``events.list`` endpoint for a single calendar.
+
+ Parameters
+ ----------
+ token:
+ OAuth access token.
+ calendar_id:
+ Calendar identifier (e.g. ``"primary"``).
+ page_token:
+ Pagination token from a previous response's ``nextPageToken``.
+ time_min:
+ Lower bound (exclusive) for an event's end time (RFC3339 timestamp).
+ When omitted the API returns all events.
+
+ Returns
+ -------
+ dict
+ Raw API response containing an ``items`` list and optional
+ ``nextPageToken``.
+ """
+ params: Dict[str, Any] = {
+ "singleEvents": "true",
+ "orderBy": "startTime",
+ "maxResults": 250,
+ }
+ if page_token:
+ params["pageToken"] = page_token
+ if time_min:
+ params["timeMin"] = time_min
+
+ resp = httpx.get(
+ f"{_GCAL_API_BASE}/calendars/{calendar_id}/events",
+ headers={"Authorization": f"Bearer {token}"},
+ params=params,
+ timeout=30.0,
+ )
+ resp.raise_for_status()
+ return resp.json()
+
+
+# ---------------------------------------------------------------------------
+# Helper functions
+# ---------------------------------------------------------------------------
+
+
+def _format_event(event: Dict[str, Any]) -> str:
+ """Return a human-readable text representation of a calendar event.
+
+ Parameters
+ ----------
+ event:
+ Raw event resource dict from the Calendar API.
+
+ Returns
+ -------
+ str
+ Multi-line formatted text suitable for indexing.
+ """
+ lines: List[str] = []
+
+ summary = event.get("summary", "(No title)")
+ lines.append(f"Title: {summary}")
+
+ # When
+ start = event.get("start", {})
+ end = event.get("end", {})
+ start_str = start.get("dateTime") or start.get("date", "")
+ end_str = end.get("dateTime") or end.get("date", "")
+ if start_str or end_str:
+ lines.append(f"When: {start_str} – {end_str}")
+
+ # Location
+ location = event.get("location", "")
+ if location:
+ lines.append(f"Location: {location}")
+
+ # Organizer
+ organizer = event.get("organizer", {})
+ organizer_name = organizer.get("displayName") or organizer.get("email", "")
+ if organizer_name:
+ lines.append(f"Organizer: {organizer_name}")
+
+ # Attendees
+ attendees: List[Dict[str, Any]] = event.get("attendees", [])
+ if attendees:
+ attendee_names = [a.get("displayName") or a.get("email", "") for a in attendees]
+ lines.append(f"Attendees: {', '.join(attendee_names)}")
+
+ # Description
+ description = event.get("description", "")
+ if description:
+ lines.append(f"Description: {description}")
+
+ return "\n".join(lines)
+
+
+def _parse_event_timestamp(event: Dict[str, Any]) -> datetime:
+ """Extract the start datetime from an event resource.
+
+ Falls back to :func:`datetime.now` if the field is missing or unparseable.
+ """
+ start = event.get("start", {})
+ date_time_str: str = start.get("dateTime", "")
+ if not date_time_str:
+ return datetime.now()
+ try:
+ # RFC3339 — Python 3.11+ fromisoformat handles the trailing 'Z'.
+ # For older versions we replace 'Z' with '+00:00'.
+ normalized = date_time_str.replace("Z", "+00:00")
+ return datetime.fromisoformat(normalized)
+ except (ValueError, TypeError):
+ return datetime.now()
+
+
+# ---------------------------------------------------------------------------
+# GCalendarConnector
+# ---------------------------------------------------------------------------
+
+
[email protected]("gcalendar")
+class GCalendarConnector(BaseConnector):
+ """Connector that syncs events from Google Calendar via the REST API v3.
+
+ Authentication is handled through Google OAuth 2.0. Tokens are stored
+ locally in a JSON credentials file.
+
+ Parameters
+ ----------
+ credentials_path:
+ Path to the JSON file where OAuth tokens are stored. Defaults to
+ ``~/.openjarvis/connectors/gcalendar.json``.
+ """
+
+ connector_id = "gcalendar"
+ display_name = "Google Calendar"
+ auth_type = "oauth"
+
+ def __init__(self, credentials_path: str = "") -> None:
+ self._credentials_path = credentials_path or _DEFAULT_CREDENTIALS_PATH
+ self._items_synced: int = 0
+ self._items_total: int = 0
+ self._last_sync: Optional[datetime] = None
+ self._last_cursor: Optional[str] = None
+
+ # ------------------------------------------------------------------
+ # BaseConnector interface
+ # ------------------------------------------------------------------
+
+ def is_connected(self) -> bool:
+ """Return ``True`` if a credentials file with a valid token exists."""
+ tokens = load_tokens(self._credentials_path)
+ if tokens is None:
+ return False
+ return bool(tokens)
+
+ def disconnect(self) -> None:
+ """Delete the stored credentials file."""
+ delete_tokens(self._credentials_path)
+
+ def auth_url(self) -> str:
+ """Return a Google OAuth consent URL requesting ``calendar.readonly`` scope."""
+ return build_google_auth_url(
+ client_id="", # placeholder — real client_id from config
+ scopes=[_GCAL_SCOPE],
+ )
+
+ def handle_callback(self, code: str) -> None:
+ """Handle the OAuth callback by persisting the authorization code.
+
+ In a full implementation this would exchange the code for tokens.
+ For now the code is saved directly as the token value.
+ """
+ save_tokens(self._credentials_path, {"token": code})
+
+ def sync(
+ self,
+ *,
+ since: Optional[datetime] = None, # noqa: ARG002 — reserved for future use
+ cursor: Optional[str] = None,
+ ) -> Iterator[Document]:
+ """Yield :class:`Document` objects for Google Calendar events.
+
+ Fetches all calendars from the calendarList endpoint, then paginates
+ through each calendar's events.
+
+ Parameters
+ ----------
+ since:
+ Not yet used (filtering is done server-side via ``timeMin``).
+ cursor:
+ ``nextPageToken`` from a previous sync to resume pagination.
+ """
+ tokens = load_tokens(self._credentials_path)
+ if not tokens:
+ return
+
+ token: str = tokens.get("token", tokens.get("access_token", ""))
+ if not token:
+ return
+
+ # Fetch list of calendars
+ calendars_resp = _gcal_api_calendars_list(token)
+ calendars: List[Dict[str, Any]] = calendars_resp.get("items", [])
+
+ synced = 0
+
+ for calendar in calendars:
+ calendar_id: str = calendar.get("id", "")
+ if not calendar_id:
+ continue
+
+ page_token: Optional[str] = cursor
+
+ while True:
+ events_resp = _gcal_api_events_list(
+ token, calendar_id, page_token=page_token
+ )
+ events: List[Dict[str, Any]] = events_resp.get("items", [])
+
+ for event in events:
+ evt_id: str = event.get("id", "")
+ if not evt_id:
+ continue
+
+ summary: str = event.get("summary", "")
+ organizer: Dict[str, Any] = event.get("organizer", {})
+ organizer_email: str = organizer.get("email", "")
+ attendees: List[Dict[str, Any]] = event.get("attendees", [])
+ participant_emails: List[str] = [
+ a.get("email", "") for a in attendees if a.get("email")
+ ]
+ timestamp = _parse_event_timestamp(event)
+ html_link: Optional[str] = event.get("htmlLink")
+
+ content = _format_event(event)
+
+ doc = Document(
+ doc_id=f"gcalendar:{evt_id}",
+ source="gcalendar",
+ doc_type="event",
+ content=content,
+ title=summary,
+ author=organizer_email,
+ participants=participant_emails,
+ timestamp=timestamp,
+ url=html_link,
+ metadata={
+ "calendar_id": calendar_id,
+ "event_id": evt_id,
+ },
+ )
+ synced += 1
+ yield doc
+
+ next_page: Optional[str] = events_resp.get("nextPageToken")
+ if not next_page:
+ self._last_cursor = None
+ break
+ page_token = next_page
+ self._last_cursor = next_page
+
+ self._items_synced = synced
+ self._last_sync = datetime.now()
+
+ def sync_status(self) -> SyncStatus:
+ """Return sync progress from the most recent :meth:`sync` call."""
+ return SyncStatus(
+ state="idle",
+ items_synced=self._items_synced,
+ last_sync=self._last_sync,
+ cursor=self._last_cursor,
+ )
+
+ # ------------------------------------------------------------------
+ # MCP tools
+ # ------------------------------------------------------------------
+
+ def mcp_tools(self) -> List[ToolSpec]:
+ """Expose three MCP tool specs for real-time Google Calendar queries."""
+ return [
+ ToolSpec(
+ name="calendar_get_events_today",
+ description=(
+ "Retrieve all Google Calendar events scheduled for today. "
+ "Returns a list of events with title, time, location, "
+ "and attendees."
+ ),
+ parameters={
+ "type": "object",
+ "properties": {
+ "calendar_id": {
+ "type": "string",
+ "description": (
+ "Calendar ID to query. Defaults to 'primary'."
+ ),
+ "default": "primary",
+ },
+ },
+ "required": [],
+ },
+ category="productivity",
+ ),
+ ToolSpec(
+ name="calendar_search_events",
+ description=(
+ "Search Google Calendar events by keyword. "
+ "Matches against event titles, descriptions, and locations."
+ ),
+ parameters={
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Search term to match against event fields",
+ },
+ "max_results": {
+ "type": "integer",
+ "description": "Maximum number of events to return",
+ "default": 20,
+ },
+ "calendar_id": {
+ "type": "string",
+ "description": (
+ "Calendar ID to search. Defaults to 'primary'."
+ ),
+ "default": "primary",
+ },
+ },
+ "required": ["query"],
+ },
+ category="productivity",
+ ),
+ ToolSpec(
+ name="calendar_next_meeting",
+ description=(
+ "Find the next upcoming meeting on the user's Google Calendar. "
+ "Returns title, start time, location, and attendees."
+ ),
+ parameters={
+ "type": "object",
+ "properties": {
+ "calendar_id": {
+ "type": "string",
+ "description": (
+ "Calendar ID to query. Defaults to 'primary'."
+ ),
+ "default": "primary",
+ },
+ },
+ "required": [],
+ },
+ category="productivity",
+ ),
+ ]
diff --git a/tests/connectors/test_gcalendar.py b/tests/connectors/test_gcalendar.py
new file mode 100644
index 00000000..05e6a5d6
--- /dev/null
+++ b/tests/connectors/test_gcalendar.py
@@ -0,0 +1,177 @@
+"""Tests for GCalendarConnector — OAuth-authenticated Google Calendar sync connector.
+
+All Calendar API calls are mocked; no network access is required.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import List
+from unittest.mock import patch
+
+import pytest
+
+from openjarvis.connectors._stubs import Document
+from openjarvis.core.registry import ConnectorRegistry
+
+# ---------------------------------------------------------------------------
+# Helpers — fake API payloads
+# ---------------------------------------------------------------------------
+
+_CALENDARS_RESPONSE = {"items": [{"id": "primary", "summary": "My Calendar"}]}
+
+_EVENTS_RESPONSE = {
+ "items": [
+ {
+ "id": "evt1",
+ "summary": "Sprint Planning",
+ "description": "Review sprint goals and capacity.",
+ "start": {"dateTime": "2024-03-15T10:00:00Z"},
+ "end": {"dateTime": "2024-03-15T11:00:00Z"},
+ "attendees": [
+ {"email": "[email protected]", "displayName": "Alice"},
+ {"email": "[email protected]", "displayName": "Bob"},
+ ],
+ "location": "Room 3",
+ "organizer": {"email": "[email protected]", "displayName": "Alice"},
+ "htmlLink": "https://calendar.google.com/event?eid=evt1",
+ }
+ ],
+ "nextPageToken": None,
+}
+
+
+def _make_credentials(tmp_path: Path) -> Path:
+ """Write a minimal fake credentials file and return its path."""
+ creds = tmp_path / "gcalendar.json"
+ creds.write_text(json.dumps({"token": "fake-access-token"}), encoding="utf-8")
+ return creds
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+def connector(tmp_path: Path):
+ """GCalendarConnector pointing at a tmp credentials path (no file yet)."""
+ from openjarvis.connectors.gcalendar import GCalendarConnector # noqa: PLC0415
+
+ creds_path = str(tmp_path / "gcalendar.json")
+ return GCalendarConnector(credentials_path=creds_path)
+
+
+# ---------------------------------------------------------------------------
+# Test 1 — not connected without a credentials file
+# ---------------------------------------------------------------------------
+
+
+def test_not_connected(connector) -> None:
+ """is_connected() returns False when no credentials file exists."""
+ assert connector.is_connected() is False
+
+
+# ---------------------------------------------------------------------------
+# Test 2 — auth_url contains calendar.readonly scope
+# ---------------------------------------------------------------------------
+
+
+def test_auth_url(connector) -> None:
+ """auth_url() returns a URL to Google's OAuth endpoint with calendar scope."""
+ url = connector.auth_url()
+ assert isinstance(url, str)
+ assert url.startswith("https://accounts.google.com/o/oauth2/v2/auth")
+ assert "calendar.readonly" in url
+
+
+# ---------------------------------------------------------------------------
+# Test 3 — sync yields events with correct fields (mocked API)
+# ---------------------------------------------------------------------------
+
+
+@patch("openjarvis.connectors.gcalendar._gcal_api_calendars_list")
+@patch("openjarvis.connectors.gcalendar._gcal_api_events_list")
+def test_sync_yields_events(
+ mock_events,
+ mock_calendars,
+ connector,
+ tmp_path: Path,
+) -> None:
+ """sync() yields one Document per event with correct metadata."""
+ # Set up fake credentials so is_connected() returns True
+ creds_path = Path(connector._credentials_path)
+ creds_path.write_text(json.dumps({"token": "fake-access-token"}), encoding="utf-8")
+
+ # Configure mocks
+ mock_calendars.return_value = _CALENDARS_RESPONSE
+ mock_events.return_value = _EVENTS_RESPONSE
+
+ docs: List[Document] = list(connector.sync())
+
+ assert len(docs) == 1
+
+ doc = docs[0]
+ assert doc.doc_id == "gcalendar:evt1"
+ assert doc.source == "gcalendar"
+ assert doc.doc_type == "event"
+ assert doc.title == "Sprint Planning"
+ assert doc.author == "[email protected]"
+ assert "[email protected]" in doc.participants
+ assert "[email protected]" in doc.participants
+ assert "Room 3" in doc.content
+ assert doc.url == "https://calendar.google.com/event?eid=evt1"
+
+ # Verify the API was called correctly
+ mock_calendars.assert_called_once()
+ mock_events.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Test 4 — disconnect removes the credentials file
+# ---------------------------------------------------------------------------
+
+
+def test_disconnect(connector, tmp_path: Path) -> None:
+ """disconnect() deletes the credentials file."""
+ creds_path = Path(connector._credentials_path)
+ creds_path.write_text(json.dumps({"token": "fake-access-token"}), encoding="utf-8")
+ assert connector.is_connected() is True
+
+ connector.disconnect()
+
+ assert not creds_path.exists()
+ assert connector.is_connected() is False
+
+
+# ---------------------------------------------------------------------------
+# Test 5 — mcp_tools returns the three expected tool specs
+# ---------------------------------------------------------------------------
+
+
+def test_mcp_tools(connector) -> None:
+ """mcp_tools() returns exactly 3 tools with the required names."""
+ tools = connector.mcp_tools()
+ names = {t.name for t in tools}
+ assert len(tools) == 3
+ assert "calendar_get_events_today" in names
+ assert "calendar_search_events" in names
+ assert "calendar_next_meeting" in names
+
+
+# ---------------------------------------------------------------------------
+# Test 6 — ConnectorRegistry contains "gcalendar" after import
+# ---------------------------------------------------------------------------
+
+
+def test_registry() -> None:
+ """GCalendarConnector can be registered and retrieved via ConnectorRegistry."""
+ from openjarvis.connectors.gcalendar import GCalendarConnector # noqa: PLC0415
+
+ # The registry is cleared before each test by the autouse conftest fixture,
+ # so we imperatively re-register here (same pattern as test_gmail.py).
+ ConnectorRegistry.register_value("gcalendar", GCalendarConnector)
+ assert ConnectorRegistry.contains("gcalendar")
+ cls = ConnectorRegistry.get("gcalendar")
+ assert cls.connector_id == "gcalendar"