Connectors

CRM connector primitives. Pull/push records from commercial CRMs (Salesforce, HubSpot, Zoho, Microsoft Dynamics 365) through a unified ConnectorProtocol.

CRM connector primitives — lazy-loaded.

Pull/push records from commercial CRMs (Salesforce, HubSpot, Zoho, Microsoft Dynamics 365) through a unified ConnectorProtocol. CRM data flows into the analytics pipeline — normalize via identifiers/, enrich via geo/, visualize via reporting/.

See docs/epics/CRM_INTEGRATIONS_EPIC.md for the full epic.

Protocol

Connector protocol and shared types for CRM integrations.

Defines the contract that all CRM connectors satisfy, plus supporting types for bulk operations and error handling. Follows the Gazetteer Protocol pattern (geo.gazetteers.base): narrow, runtime-checkable, intentionally minimal.

Connectors are primitives — pull/push records. Transformation lives in identifiers/, geo/, reporting/. No sync scheduling, no CDC, no conflict resolution beyond dedup.

class siege_utilities.connectors._protocol.ConnectorProtocol

Bases: Protocol

CRM connector contract.

The protocol is intentionally narrow — eight methods. Backends layer OAuth token refresh, rate-limit backoff, pagination, and other plumbing internally; callers just see this surface.

Each connector may expose vendor-specific methods beyond the protocol (e.g., SalesforceConnector.soql()). The protocol captures the shared shape that reporting, dedup, and enrichment pipelines depend on.

property provider_name: str

Human-readable backend identifier ("salesforce", etc.).

authenticate()

Establish an authenticated session.

Raises:

ConnectorAuthError – credentials invalid or auth flow failed.

Return type:

None

is_connected()

Whether the connector has an active, authenticated session.

Return type:

bool

list_object_types()

Available object types (["Contact", "Account", ...]).

Return type:

list[str]

get_objects(object_type, *, fields=None, filters=None, limit=None)

Fetch records of object_type as a DataFrame.

Parameters:

• object_type (str) – CRM object name ("Contact", "Opportunity").

• fields (list[str] | None) – Columns to return. None for a sensible default set.

• filters (dict[str, Any] | None) – Key-value filter criteria (interpretation is connector-specific).

• limit (int | None) – Maximum records to return. None for all.

Raises:

• ConnectorNotFoundError – object_type does not exist.

• ConnectorAuthError – session expired or insufficient permissions.

• ConnectorRateLimitError – API rate limit hit.

Return type:

pandas.DataFrame

create_record(object_type, data)

Create a single record; return its ID.

Raises:

ConnectorError – validation or API failure (never silent).

Parameters:

• object_type (str)

• data (dict[str, Any])

Return type:

str

update_record(object_type, record_id, data)

Update a single record; return True on success.

Raises on failure — never returns False silently (SU-1).

Parameters:

• object_type (str)

• record_id (str)

• data (dict[str, Any])

Return type:

bool

upsert_records(object_type, records, match_field)

Bulk create-or-update from a DataFrame.

Parameters:

• object_type (str) – Target CRM object.

• records (pandas.DataFrame) – DataFrame whose columns map to CRM fields.

• match_field (str) – Column used to match existing records (e.g., "email" for contacts).

Returns:

UpsertResult with per-record outcome.

Raises:

• ConnectorAuthError – session expired.

• ConnectorRateLimitError – API rate limit hit.

Return type:

UpsertResult

__init__(*args, **kwargs)

class siege_utilities.connectors._protocol.UpsertResult

Bases: object

Outcome of a bulk upsert operation.

Never silent — failure_count == 0 is the only success signal. Callers must check errors when failure_count > 0 (SU-1).

success_count: int

failure_count: int

created_ids: list[str]

updated_ids: list[str]

errors: list[UpsertError]

property total: int

property ok: bool

__init__(success_count, failure_count, created_ids=<factory>, updated_ids=<factory>, errors=<factory>)

Parameters:

• success_count (int)

• failure_count (int)

• created_ids (list[str])

• updated_ids (list[str])

• errors (list[UpsertError])

Return type:

None

class siege_utilities.connectors._protocol.UpsertError

Bases: object

One failed record in a bulk upsert.

record_index: int

message: str

field: str | None = None

code: str | None = None

__init__(record_index, message, field=None, code=None)

Parameters:

• record_index (int)

• message (str)

• field (str | None)

• code (str | None)

Return type:

None

exception siege_utilities.connectors._protocol.ConnectorError

Bases: Exception

Base for all connector errors.

exception siege_utilities.connectors._protocol.ConnectorAuthError

Bases: ConnectorError

Authentication or authorization failure.

exception siege_utilities.connectors._protocol.ConnectorRateLimitError

Bases: ConnectorError

API rate limit exceeded.

__init__(message, retry_after=None)

Parameters:

• message (str)

• retry_after (float | None)

Return type:

None

exception siege_utilities.connectors._protocol.ConnectorNotFoundError

Bases: ConnectorError

Requested object type or record not found.