[Feature] Add a Google People contacts connector #18

New Issue

2026-08-02T07:07:23+02:00

zemion commented

2026-08-02 07:07:23 +02:00

Goal

Synchronize Google contact sources through a dedicated Addresses connector with explicit authority and evidence.

Parent: #8. Related shared runtime: GovOPlaN/govoplan-connectors#8.

Direction And Boundary

Deliver read-only/import first; enable governed two-way mode only after write/reconciliation tests pass.
Keep Google account/credential handling in reusable credential envelopes and connector configuration.
No hard dependency on Mail, Calendar, Access, or IDM.

Scope

OAuth credential reference, account/contact-group discovery, scope diagnostics, and source configuration UI.
Bounded paging and incremental refresh state with explicit token expiry/full-resync handling.
Dry-run create/update/delete plan, source freshness, rate-limit/backoff, tombstones, conflicts, and outcome-unknown reconciliation.
Contact/group field mapping with original remote representation, normalized values, stable references, and field provenance.
Fake-provider contract tests for pagination, expired authorization, throttling, stale revisions, deletions, partial failures, and idempotency.
Setup, permission, authority, and disconnect documentation.

Acceptance Criteria

Operators can discover and preview a source before any contact mutation.
Read-only refresh is bounded and idempotent, and outages make freshness explicit.
Two-way mode is unavailable until conditional writes and ambiguous outcomes are reconciled safely.
Disabling the connector leaves local evidence understandable and removes owned credentials according to the credential contract.

## Goal Synchronize Google contact sources through a dedicated Addresses connector with explicit authority and evidence. Parent: #8. Related shared runtime: GovOPlaN/govoplan-connectors#8. ## Direction And Boundary - Deliver read-only/import first; enable governed two-way mode only after write/reconciliation tests pass. - Keep Google account/credential handling in reusable credential envelopes and connector configuration. - No hard dependency on Mail, Calendar, Access, or IDM. ## Scope - OAuth credential reference, account/contact-group discovery, scope diagnostics, and source configuration UI. - Bounded paging and incremental refresh state with explicit token expiry/full-resync handling. - Dry-run create/update/delete plan, source freshness, rate-limit/backoff, tombstones, conflicts, and outcome-unknown reconciliation. - Contact/group field mapping with original remote representation, normalized values, stable references, and field provenance. - Fake-provider contract tests for pagination, expired authorization, throttling, stale revisions, deletions, partial failures, and idempotency. - Setup, permission, authority, and disconnect documentation. ## Acceptance Criteria - Operators can discover and preview a source before any contact mutation. - Read-only refresh is bounded and idempotent, and outages make freshness explicit. - Two-way mode is unavailable until conditional writes and ambiguous outcomes are reconciled safely. - Disabling the connector leaves local evidence understandable and removes owned credentials according to the credential contract.