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.

10.1 KB
Raw Blame
from typing import Optional, cast

from products.warehouse_sources.sources.plausible._config import PlausibleSourceConfig
from products.warehouse_sources.sources.plausible.plausible import (
    PlausibleResumeConfig,
    hostname_of,
    plausible_source,
    validate_credentials as validate_plausible_credentials,
)
from products.warehouse_sources.sources.plausible.settings import (
    ENDPOINTS,
    custom_property_endpoint_name,
    get_endpoint_config,
    parse_custom_property_keys,
)
from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ProductKey,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    ValidateDatabaseHostMixin,
    detect,
)


@SourceRegistry.register
class PlausibleSource(ResumableSource[PlausibleSourceConfig, PlausibleResumeConfig], ValidateDatabaseHostMixin):
    codebase_detection = detect(
        env=("^PLAUSIBLE_", "^NUXT_PUBLIC_PLAUSIBLE_"),
        script_hosts=("plausible.io",),
        npm=(
            "plausible-tracker",
            "@plausible-analytics/tracker",
            "next-plausible",
            "@nuxtjs/plausible",
            "vue-plausible",
            "v-plausible",
            "gatsby-plugin-plausible",
            "vuepress-plugin-plausible",
            "gridsome-plugin-plausible-analytics",
        ),
        pypi=("django-plausible", "django-plausible-proxy", "sphinx-plausible"),
        composer=("vincentbean/laravel-plausible", "njoguamos/laravel-plausible"),
        go=("github.com/andrerfcsantos/go-plausible",),
        hex=("plausible",),
        pub=("plausible_analytics", "plausible"),
        rubygems=("plausible_api", "bridgetown-plausible"),
        swiftpm=("github.com/nickoneill/plausibleswift", "github.com/brightdigit/aviaryinsights"),
        alternative_to=(ProductKey.WEB_ANALYTICS,),
    )

    supported_versions = ("v2",)
    default_version = "v2"
    api_docs_url = "https://plausible.io/docs/stats-api"

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

    @property
    def connection_host_fields(self) -> list[str]:
        # `host` determines where the stored API key is sent; retargeting it must re-require the key.
        return ["host"]

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "401 Client Error": "Your Plausible API key is invalid or has been revoked. Create a new key in your Plausible account settings, then reconnect.",
            "403 Client Error": "Your Plausible API key is missing the stats read scope needed to sync this data. Grant it in your Plausible account settings, then reconnect.",
            # Plausible answers 402 when the site's subscription has lapsed or its plan doesn't
            # include the stats API. The billing state is fixed until the customer changes it, so
            # every retry replays the same rejection. Match the status text, not the self-hosted URL.
            "402 Client Error": "Your Plausible plan doesn't include API access, or its subscription has lapsed. Update the subscription in your Plausible account, then reconnect.",
            # Plausible rejects the query as malformed for this site (a permanent 400 — auth and
            # missing-site cases are 401/403/404 and handled above). Retrying resends the same
            # request, so stop. Match the status text, not the self-hosted URL, which varies.
            "400 Client Error": "Plausible rejected the request for this site. Check that the site domain is correct and that your Plausible account can access its stats, then reconnect.",
            # `is_database_host_valid` raises this when the self-hosted Host doesn't resolve via
            # DNS — a hostname the customer typed wrong or one that's no longer publicly reachable.
            # Deterministic and permanent until the Host is corrected, so stop retrying. Match the
            # stable prefix, not the customer's hostname that follows it.
            "Couldn't resolve the host": "The Plausible host could not be resolved via DNS. Check that it's spelled correctly and reachable from the public internet, then reconnect.",
        }

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.PLAUSIBLE,
            category=DataWarehouseSourceCategory.ANALYTICS,
            label="Plausible",
            caption="""Connect Plausible Analytics to pull your web analytics into the PostHog Data warehouse.

Works with Plausible Cloud and self-hosted instances. Create an API key under **Account settings → API keys** with the `stats read` scope, then enter your site's domain (e.g. `example.com`). Leave the host blank for Plausible Cloud, or set it to your instance URL for self-hosted (e.g. `https://plausible.example.com`).""",
            iconPath="/static/services/plausible.png",
            docsUrl="https://posthog.com/docs/cdp/sources/plausible",
            releaseStatus=ReleaseStatus.GA,
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_key",
                        label="API key",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                    SourceFieldInputConfig(
                        name="site_id",
                        label="Site domain",
                        type=SourceFieldInputConfigType.TEXT,
                        required=True,
                        placeholder="example.com",
                        secret=False,
                    ),
                    SourceFieldInputConfig(
                        name="host",
                        label="Host (self-hosted only)",
                        type=SourceFieldInputConfigType.TEXT,
                        required=False,
                        placeholder="https://plausible.io",
                        secret=False,
                    ),
                    SourceFieldInputConfig(
                        name="custom_property_keys",
                        sync_setting=True,
                        label="Custom property keys",
                        caption="Optional. A comma-separated list of the custom properties to sync, for example `plan, signup_method`. Each property syncs as its own table. Your Plausible plan needs to include custom properties.",
                        type=SourceFieldInputConfigType.TEXT,
                        required=False,
                        placeholder="plan, signup_method",
                        secret=False,
                    ),
                ],
            ),
        )

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

        return CANONICAL_DESCRIPTIONS

    def get_schemas(
        self,
        config: PlausibleSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        def _build_schema(endpoint: str) -> SourceSchema:
            endpoint_config = get_endpoint_config(endpoint)
            return SourceSchema(
                name=endpoint,
                # date_range is a genuine server-side filter, so every report supports incremental
                # syncing by sliding the window forward.
                supports_incremental=True,
                supports_append=True,
                incremental_fields=endpoint_config.incremental_fields,
                should_sync_default=endpoint_config.should_sync_default,
            )

        custom_property_endpoints = [
            custom_property_endpoint_name(key) for key in parse_custom_property_keys(config.custom_property_keys)
        ]
        schemas = [_build_schema(endpoint) for endpoint in [*ENDPOINTS, *custom_property_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: PlausibleSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        try:
            host_valid, host_error = self.is_database_host_valid(hostname_of(config.host), team_id)
        except ValueError:
            return False, "Invalid Plausible host URL"
        if not host_valid:
            return False, host_error

        return validate_plausible_credentials(config.host, config.site_id, config.api_key)

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

    def source_for_pipeline(
        self,
        config: PlausibleSourceConfig,
        resumable_source_manager: ResumableSourceManager[PlausibleResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        host_valid, host_error = self.is_database_host_valid(hostname_of(config.host), inputs.team_id)
        if not host_valid:
            raise ValueError(host_error or "Invalid Plausible host")

        return plausible_source(
            host=config.host,
            site_id=config.site_id,
            api_key=config.api_key,
            endpoint=inputs.schema_name,
            team_id=inputs.team_id,
            job_id=inputs.job_id,
            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,
        )