effaced-intercom

effaced-intercom — the first-party Intercom resolver for effaced.

IntercomResolver

class IntercomResolver:
    def __init__(access_token: str, *, base_url: str = _DEFAULT_BASE_URL, transport: httpx.BaseTransport | None = None, timeout: float = _DEFAULT_TIMEOUT, api_version: str = _DEFAULT_API_VERSION) -> None

Exports and erases a subject’s Intercom contact and conversation metadata.

Expects refs of kind "intercom" (refs are routed to the resolver whose name equals their kind — ADR 0008) whose value is the contact’s Intercom internal id. Get and delete address the contact by id directly, so erasure needs no email lookup and no enumeration; the application resolves email-to-id in its own data map.

Export (Art. 15) collects the contact’s email, name, and phone, plus per-conversation metadata — created_at, updated_at, and state for every conversation the contact appears in (paged through POST /conversations/search). It never exports message bodies or the caller-defined custom_attributes blob. Erasure (Art. 17) hard-deletes the contact via DELETE /contacts/{id}.

Idempotency: a contact Intercom no longer knows yields already_absent=True — success, never an error.

Error taxonomy (see effaced_intercom.errors): 4xx responses other than 404 and 429 raise ResolverError; rate limits, 5xx, and connection faults propagate so the saga runner retries. A fresh httpx client is built per call — nothing loop- or connection-bound is cached on the instance (ADR 0006).

Fields:

• covered_surface (CoveredSurface): The Intercom PII this resolver claims to reach (AttestingResolver). Returns: INTERCOM_COVERED_SURFACE, built from the exporter’s field tuples so it cannot drift.
• name (str): Stable resolver name recorded in manifests and audits.

IntercomResolver.erase_subject

async def erase_subject(ref: SubjectRef) -> ResolverErasure

Hard-delete the contact in Intercom (Art. 17).

Args:

• ref (SubjectRef): kind="intercom", value=<Intercom contact id>.

Returns:

• ResolverErasure — The outcome; already_absent=True if Intercom already had
• ResolverErasure — no such contact.

Raises:

• ResolverError — The token is invalid or lacks a scope, or the request was malformed — retrying cannot succeed.

IntercomResolver.export_subject

async def export_subject(ref: SubjectRef) -> ResolverExport

Collect the contact’s profile and conversation metadata (Art. 15).

Args:

• ref (SubjectRef): kind="intercom", value=<Intercom contact id>.

Returns:

• ResolverExport — The contact’s email/name/phone and every
• ResolverExport — conversation’s created_at/updated_at/state (the
• ResolverExport — field set lives in effaced_intercom.export_records);
• ResolverExport — empty when Intercom holds no such contact.

Raises:

• ResolverError — The token is invalid or lacks a scope, or the request was malformed — retrying cannot succeed.