Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

11.7 KB
Raw Blame
from typing import cast

from products.warehouse_sources.sources.intercom._config import IntercomSourceConfig
from products.warehouse_sources.sources.intercom.intercom import (
    IntercomConversationCursor,
    IntercomResumeConfig,
    intercom_source,
    validate_credentials as validate_intercom_credentials,
)
from products.warehouse_sources.sources.intercom.settings import INCREMENTAL_FIELDS, INTERCOM_ENDPOINTS
from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    CursorSource,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    OAuthMixin,
    ProductKey,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldOauthConfig,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    detect,
)


@SourceRegistry.register
class IntercomSource(
    ResumableSource[IntercomSourceConfig, IntercomResumeConfig],
    CursorSource[IntercomConversationCursor],
    OAuthMixin,
):
    codebase_detection = detect(
        env=(
            "^INTERCOM_",
            "^IOS_INTERCOM_APP_ID$",
            "^IOS_INTERCOM_KEY$",
            "^ANDROID_INTERCOM_APP_ID$",
            "^ANDROID_INTERCOM_KEY$",
        ),
        script_hosts=("widget.intercom.io", "js.intercomcdn.com", "app.intercom.io", "static.intercomcdn.com"),
        npm=(
            "intercom-client",
            "@intercom/messenger-js-sdk",
            "@intercom/intercom-react-native",
            "react-use-intercom",
            "cordova-plugin-intercom",
            "@intercom/cli",
            "passport-intercom",
            "@types/intercom-web",
            "@types/intercom-client",
            "@capacitor-community/intercom",
            "@capgo/capacitor-intercom",
            "@awesome-cordova-plugins/intercom",
            "@ionic-native/intercom",
            "react-intercom",
            "@supy-io/ngx-intercom",
            "ng-intercom",
            "@mathieustan/vue-intercom",
        ),
        pypi=("python-intercom", "django-intercom"),
        cocoapods=("Intercom",),
        composer=("intercom/intercom-php", "intercom/oauth2-intercom"),
        go=("github.com/intercom/intercom-go", "gopkg.in/intercom/intercom-go.v2"),
        hex=("intercom",),
        maven=(
            "io.intercom.android:intercom-sdk",
            "io.intercom:intercom-java",
            "io.intercom.android:intercom-sdk-base",
            "io.intercom.android:intercom-sdk-fcm",
            "io.intercom.android:intercom-sdk-ui",
            "io.intercom.android:intercom-sdk-base-transitive",
        ),
        pub=("intercom_flutter", "intercom_flutter_web", "intercom_flutter_platform_interface"),
        rubygems=("intercom", "intercom-rails", "omniauth-intercom", "intercom-app"),
        swiftpm=("github.com/intercom/intercom-ios-sp", "github.com/intercom/intercom-ios"),
        alternative_to=(ProductKey.CONVERSATIONS,),
    )

    lists_tables_without_credentials = True  # static endpoint catalog — safe for public docs
    supported_versions = ("2.13", "2.15", "2.16", "2.17")
    default_version = "2.17"
    api_docs_url = "https://developers.intercom.com/docs/references/rest-api"

    @property
    def source_type(self) -> ExternalDataSourceType:
        return ExternalDataSourceType.INTERCOM

    def get_canonical_descriptions(self) -> CanonicalDescriptions:
        from products.warehouse_sources.sources.intercom.canonical_descriptions import CANONICAL_DESCRIPTIONS

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "401 Client Error": "Your Intercom connection is invalid or expired. Please reconnect it.",
            "403 Client Error": "Your Intercom connection is missing required scopes. Please update permissions and reconnect.",
            # Deterministic credential/config errors from OAuthMixin and source_for_pipeline. The
            # integration row is gone or unconfigured, so retrying can never succeed — the customer
            # must reconnect. Match on the stable prefix so the volatile integration ID is ignored.
            "Missing integration ID": "Intercom integration ID is not configured. Please reconnect your Intercom account.",
            "Integration not found": "The linked Intercom integration no longer exists. Please reconnect your Intercom account.",
            "Intercom access token not found": "Intercom OAuth access token is missing. Please reconnect your Intercom account.",
            # Raised by intercom_source for a table Intercom only serves on a newer API version.
            "requires Intercom API version": "This table needs a newer Intercom API version. Upgrade the source's API version, then sync again.",
        }

    def resume_covers_run(
        self,
        *,
        incremental_or_append: bool,
        schema_name: str | None = None,
    ) -> bool:
        # The companies Scroll API cannot preserve a cursor across worker hand-offs.
        return schema_name != "companies"

    def get_retryable_errors(self) -> set[str]:
        # The `companies` table walks Intercom's companies Scroll API (`_iter_companies` in
        # intercom.py). The scroll cursor expires mid-walk on idle timeout or when a
        # concurrent sync steals the workspace's single scroll slot, and the continuation
        # then 404s (see `_is_scroll_expired`). `companies` is full-refresh, so a fresh
        # Temporal attempt opens a new scroll and restarts cleanly — transient and
        # self-recovering, not a real bug.
        #
        # Opening a fresh scroll can also 400 with `scroll_exists` when another scroll is
        # still open for the workspace (see `_is_scroll_exists`). `_open_companies_scroll`
        # already backs off and retries that inline, but a lock held longer than the retry
        # budget exhausts it and the raw error propagates — a fresh Temporal attempt opens
        # cleanly once the stale scroll has expired, so this is the same self-recovering
        # case as the 404 above, just surfaced later.
        return {
            "Not Found for url: https://api.intercom.io/companies/scroll",
            "Bad Request for url: https://api.intercom.io/companies/scroll",
            # Every Intercom request goes through `_make_intercom_session`, whose transport-level
            # retry (`_INTERCOM_RETRY`, derived from `DEFAULT_RETRY`) already retries a 429/5xx
            # response before `raise_for_status` can raise. A `HTTPError` reaching here has already
            # exhausted that budget, so it's a transient upstream blip — Temporal retries the whole
            # activity next. `raise_for_status` derives the "Server Error" prefix from the status
            # code alone, not Intercom's reason text, so it's stable to match on (see
            # convex/app_store_connect for the same pattern).
            "Server Error",
        }

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.INTERCOM,
            category=DataWarehouseSourceCategory.CUSTOMER_SUPPORT,
            caption="Select an existing Intercom workspace to link to PostHog or create a new connection",
            iconPath="/static/services/intercom.png",
            docsUrl="https://posthog.com/docs/cdp/sources/intercom",
            fields=cast(
                list[FieldType],
                [
                    SourceFieldOauthConfig(
                        name="intercom_integration_id",
                        label="Intercom workspace",
                        required=True,
                        kind="intercom",
                    ),
                ],
            ),
            releaseStatus=ReleaseStatus.GA,
        )

    def get_schemas(
        self,
        config: IntercomSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        resolved_version = self.resolve_api_version(api_version)
        schemas = []
        for endpoint_config in INTERCOM_ENDPOINTS.values():
            if endpoint_config.api_versions is not None and resolved_version not in endpoint_config.api_versions:
                continue
            incremental_fields = INCREMENTAL_FIELDS.get(endpoint_config.name, [])
            supports_incremental = bool(incremental_fields)
            schemas.append(
                SourceSchema(
                    name=endpoint_config.name,
                    supports_incremental=supports_incremental,
                    supports_append=supports_incremental,
                    incremental_fields=incremental_fields,
                )
            )
        if names is not None:
            names_set = set(names)
            schemas = [s for s in schemas if s.name in names_set]
        return schemas

    def validate_credentials(
        self, config: IntercomSourceConfig, team_id: int, schema_name: str | None = None, api_version: str | None = None
    ) -> tuple[bool, str | None]:
        try:
            integration = self.get_oauth_integration(config.intercom_integration_id, team_id)
        except ValueError:
            # get_oauth_integration raises ValueError("Integration not found: <id>") for an
            # integration that was deleted or disconnected while the source still references it.
            return False, "Intercom integration not found. Please reconnect your Intercom integration."

        if not integration.access_token:
            return False, "Intercom integration has no access token. Please reconnect."

        # Probe under the source's resolved pin so a 2.13-pinned source validates against the
        # version it syncs on; `None` (pre-creation) resolves to `default_version`.
        return validate_intercom_credentials(
            integration.access_token, schema_name=schema_name, api_version=self.resolve_api_version(api_version)
        )

    def cursor_class(self) -> type[IntercomConversationCursor]:
        return IntercomConversationCursor

    def merge_cursors(
        self, current: IntercomConversationCursor, candidate: IntercomConversationCursor
    ) -> IntercomConversationCursor:
        return max(current, candidate, key=lambda cursor: cursor.updated_at)

    def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[IntercomResumeConfig]:
        return ResumableSourceManager[IntercomResumeConfig](inputs, IntercomResumeConfig)

    def source_for_pipeline(
        self,
        config: IntercomSourceConfig,
        resumable_source_manager: ResumableSourceManager[IntercomResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        integration = self.get_oauth_integration(config.intercom_integration_id, inputs.team_id)

        if not integration.access_token:
            raise ValueError(f"Intercom access token not found for job {inputs.job_id}")

        return intercom_source(
            access_token=integration.access_token,
            endpoint=inputs.schema_name,
            team_id=inputs.team_id,
            job_id=inputs.job_id,
            api_version=self.resolve_api_version(inputs.api_version),
            resumable_source_manager=resumable_source_manager,
            should_use_incremental_field=inputs.should_use_incremental_field,
            incremental_field=inputs.incremental_field if inputs.should_use_incremental_field else None,
            db_incremental_field_last_value=inputs.db_incremental_field_last_value
            if inputs.should_use_incremental_field
            else None,
            # Only the HITL events table keeps a source cursor; see `_conversation_hitl_events_generator`.
            cursor_manager=self.get_cursor_manager(inputs)
            if inputs.schema_name == "conversation_hitl_events"
            else None,
        )