Skip to content

gcontacts

diapason.connectors.gcontacts

Google Contacts connector — bulk contact sync via the People REST API v1.

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

GContactsConnector

Bases: BaseConnector

Connector that syncs contacts from Google Contacts via the People API v1.

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/gcontacts.json.

auth_url()

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

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 two MCP tool specs for real-time Google Contacts queries.

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

Yield :class:Document objects for Google Contacts.

Paginates through the people/me/connections endpoint and converts each person resource into a Document.

Parameters

since: Not yet used (People API does not support server-side date filtering for connections). cursor: nextPageToken from a previous sync to resume pagination.

sync_status()

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