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.

6.6 KB
Raw Blame
from typing import Optional, cast

from products.warehouse_sources.sources.linkrunner._config import LinkrunnerSourceConfig
from products.warehouse_sources.sources.linkrunner.linkrunner import (
    LinkrunnerResumeConfig,
    linkrunner_source,
    validate_credentials as validate_linkrunner_credentials,
)
from products.warehouse_sources.sources.linkrunner.settings import ENDPOINTS, INCREMENTAL_FIELDS, LINKRUNNER_ENDPOINTS
from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    detect,
)


@SourceRegistry.register
class LinkrunnerSource(ResumableSource[LinkrunnerSourceConfig, LinkrunnerResumeConfig]):
    codebase_detection = detect(
        env=("^LINKRUNNER_",),
        script_hosts=("cdn.linkrunner.io",),
        npm=("rn-linkrunner", "@linkrunner/web", "capacitor-linkrunner", "cordova-linkrunner", "expo-linkrunner"),
        cocoapods=("LinkrunnerKit",),
        maven=("io.linkrunner:android-sdk",),
        pub=("linkrunner",),
        swiftpm=("github.com/linkrunner-labs/linkrunner-ios", "github.com/linkrunner-labs/capacitor-linkrunner"),
    )

    api_docs_url = "https://docs.linkrunner.io/api-reference/campaign-apis"

    lists_tables_without_credentials = True  # static endpoint catalog — safe for public docs

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

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.LINKRUNNER,
            category=DataWarehouseSourceCategory.ADVERTISING,
            label="Linkrunner",
            releaseStatus=ReleaseStatus.GA,
            caption="""Enter your Linkrunner API key to pull your mobile attribution data into the PostHog Data warehouse.

You can find your API key in your [Linkrunner dashboard](https://www.linkrunner.io/) under settings.

Note: the `reporting_campaigns` table is served by Linkrunner's Reporting API, which is rate limited to **1 request per minute**, so syncing it can take a while for accounts with many campaigns.
""",
            iconPath="/static/services/linkrunner.svg",
            docsUrl="https://posthog.com/docs/cdp/sources/linkrunner",
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_key",
                        label="API key",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                ],
            ),
        )

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

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            # An invalid or missing Linkrunner key surfaces as a 401 when `_fetch_page` calls
            # `raise_for_status()`. Retrying can never satisfy a credential problem, so stop the sync.
            "401 Client Error: Unauthorized for url: https://api.linkrunner.io": "Your Linkrunner API key is invalid or has been revoked. Create a new key in your Linkrunner dashboard, then reconnect.",
            "403 Client Error: Forbidden for url: https://api.linkrunner.io": "Your Linkrunner API key does not have access to this data. Check the key's permissions in your Linkrunner dashboard, then reconnect.",
        }

    def get_schemas(
        self,
        config: LinkrunnerSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        def _description(endpoint: str) -> str | None:
            if endpoint == "reporting_campaigns":
                return "Campaign performance metrics. Served by the rate-limited Reporting API (1 request/minute). Full refresh only."
            if endpoint == "campaigns":
                return "All campaigns in your Linkrunner account. Full refresh only."
            return None

        def _build_schema(endpoint: str) -> SourceSchema:
            endpoint_config = LINKRUNNER_ENDPOINTS[endpoint]
            has_incremental = bool(INCREMENTAL_FIELDS.get(endpoint))
            return SourceSchema(
                name=endpoint,
                supports_incremental=has_incremental,
                supports_append=has_incremental,
                incremental_fields=INCREMENTAL_FIELDS.get(endpoint, []),
                detected_primary_keys=endpoint_config.primary_keys,
                should_sync_default=endpoint_config.should_sync_default,
                description=_description(endpoint),
            )

        schemas = [_build_schema(endpoint) for endpoint in ENDPOINTS]
        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: LinkrunnerSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        if validate_linkrunner_credentials(config.api_key):
            return True, None

        return False, "Invalid Linkrunner API key"

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

    def source_for_pipeline(
        self,
        config: LinkrunnerSourceConfig,
        resumable_source_manager: ResumableSourceManager[LinkrunnerResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        return linkrunner_source(
            api_key=config.api_key,
            endpoint=inputs.schema_name,
            logger=inputs.logger,
            resumable_source_manager=resumable_source_manager,
            should_use_incremental_field=inputs.should_use_incremental_field,
            db_incremental_field_last_value=inputs.db_incremental_field_last_value
            if inputs.should_use_incremental_field
            else None,
            incremental_field=inputs.incremental_field,
        )