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.