Skip to content

gcalendar

diapason.connectors.gcalendar

Google Calendar connector — event sync via the Calendar REST API v3.

Uses OAuth 2.0 tokens stored locally (see :mod:diapason.connectors.oauth). All network calls are isolated in module-level functions (_gcal_api_*) to make them trivially mockable in tests.

GCalendarConnector

Bases: 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 ~/.diapason/connectors/gcalendar.json.

accept_event(event_id, calendar_id='primary')

Accept a calendar invite by setting responseStatus to 'accepted'.

auth_url()

Return a Google OAuth consent URL requesting calendar.readonly scope.

decline_event(event_id, calendar_id='primary')

Decline a calendar invite by setting responseStatus to 'declined'.

disconnect()

Delete the stored credentials file.

handle_callback(code)

Handle the OAuth callback.

If code looks like a client_id:client_secret pair (containing .apps.googleusercontent.com), persist the client credentials only. The browser consent + code→token exchange is owned by the in-process server flow (/v1/connectors/{id}/oauth/start → /oauth/callback), which writes the real access_token to every Google credential file.

The previous daemon-thread browser flow (its own localhost:8789 callback server) failed silently in the bundled desktop context and is intentionally removed here (issue #512).

Any other code is treated as a raw token / auth code.

is_connected()

Return True if a credentials file with a valid access token exists.

mcp_tools()

Expose three MCP tool specs for real-time Google Calendar queries.

sync(*, since=None, cursor=None)

Yield :class:Document objects for Google Calendar events.

Fetches all calendars from the calendarList endpoint, then paginates through each calendar's events.

Parameters

since: Only return events starting after this datetime. Defaults to 24 hours ago when None. cursor: nextPageToken from a previous sync to resume pagination.

sync_status()

Return sync progress from the most recent :meth:sync call.