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.2 KB
Raw Blame
from typing import Optional, cast

from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    build_endpoint_schemas,
    detect,
)
from products.warehouse_sources.sources.taboola._config import TaboolaSourceConfig
from products.warehouse_sources.sources.taboola.settings import ENDPOINTS, INCREMENTAL_FIELDS
from products.warehouse_sources.sources.taboola.taboola import (
    TaboolaResumeConfig,
    taboola_source,
    validate_credentials as validate_taboola_credentials,
)


@SourceRegistry.register
class TaboolaSource(ResumableSource[TaboolaSourceConfig, TaboolaResumeConfig]):
    codebase_detection = detect(
        env=("^TABOOLA_",),
        script_hosts=("cdn.taboola.com",),
        cocoapods=("TaboolaSDK", "TaboolaSDK2"),
        maven=("com.taboola:android-sdk", "com.taboola:taboola-cronyx", "com.taboola:taboola-cronyx-api"),
    )

    supported_versions = ("1.0",)
    default_version = "1.0"
    api_docs_url = "https://developers.taboola.com/backstage-api/reference"

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

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

    @property
    def connection_host_fields(self) -> list[str]:
        # account_id selects which Taboola account the stored credential is sent to, so
        # changing it must force re-entry of the secret (prevents credential retargeting).
        return ["account_id"]

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

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "400 Client Error: Bad Request for url: https://backstage.taboola.com/backstage/oauth/token": "Taboola rejected the token request. Please check your client ID and client secret.",
            "401 Client Error: Unauthorized for url: https://backstage.taboola.com": "Taboola authentication failed. Please check your client ID and client secret.",
            "403 Client Error: Forbidden for url: https://backstage.taboola.com": "Taboola denied access. Please check that your credentials can access this account ID.",
            "404 Client Error: Not Found for url: https://backstage.taboola.com": "Taboola account not found. Please check your account ID.",
        }

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.TABOOLA,
            category=DataWarehouseSourceCategory.ADVERTISING,
            label="Taboola",
            caption="""Connect your Taboola account to pull your advertising data into the PostHog Data warehouse.

Backstage API credentials (client ID and secret) are issued by your Taboola account manager — they can't be self-served. Your account ID is the alphabetic account identifier shown in Taboola Ads (also called the account name).""",
            iconPath="/static/services/taboola.png",
            docsUrl="https://posthog.com/docs/cdp/sources/taboola",
            releaseStatus=ReleaseStatus.GA,
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="client_id",
                        label="Client ID",
                        type=SourceFieldInputConfigType.TEXT,
                        required=True,
                        placeholder="",
                        secret=False,
                    ),
                    SourceFieldInputConfig(
                        name="client_secret",
                        label="Client secret",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                    SourceFieldInputConfig(
                        name="account_id",
                        label="Account ID",
                        type=SourceFieldInputConfigType.TEXT,
                        required=True,
                        placeholder="my-account",
                        secret=False,
                    ),
                ],
            ),
        )

    def get_schemas(
        self,
        config: TaboolaSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names)

    def validate_credentials(
        self,
        config: TaboolaSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        if validate_taboola_credentials(config.client_id, config.client_secret):
            return True, None

        return False, "Invalid Taboola credentials"

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

    def source_for_pipeline(
        self,
        config: TaboolaSourceConfig,
        resumable_source_manager: ResumableSourceManager[TaboolaResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        return taboola_source(
            client_id=config.client_id,
            client_secret=config.client_secret,
            account_id=config.account_id,
            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,
        )