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

from products.warehouse_sources.sources.clockodo._config import ClockodoSourceConfig
from products.warehouse_sources.sources.clockodo.clockodo import (
    ClockodoResumeConfig,
    clockodo_source,
    validate_credentials as validate_clockodo_credentials,
)
from products.warehouse_sources.sources.clockodo.settings import (
    CLOCKODO_API_VERSION_V2,
    CLOCKODO_DEFAULT_API_VERSION,
    CLOCKODO_SUPPORTED_VERSIONS,
    ENDPOINTS,
    INCREMENTAL_FIELDS,
    endpoints_for_version,
)
from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    VersionDeprecation,
    build_endpoint_schemas,
    detect,
)


@SourceRegistry.register
class ClockodoSource(ResumableSource[ClockodoSourceConfig, ClockodoResumeConfig]):
    codebase_detection = detect(env=("^CLOCKODO_",), npm=("clockodo",))

    lists_tables_without_credentials = True  # static endpoint catalog — safe for public docs
    supported_versions = CLOCKODO_SUPPORTED_VERSIONS
    default_version = CLOCKODO_DEFAULT_API_VERSION
    api_docs_url = "https://docs.clockodo.com/"
    # Clockodo decommissions the v2 endpoints behind six of this source's tables on 2026-05-01;
    # the generic in-product warning banner keys off this metadata.
    deprecated_versions = (VersionDeprecation(version=CLOCKODO_API_VERSION_V2, sunset_at=date(2026, 5, 1)),)

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

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            # Clockodo returns 401 both for a bad API user/key and for a missing identification
            # header; retrying can never fix either, so stop the sync. Match the stable status text
            # and base host, not the per-request path.
            "401 Client Error: Unauthorized for url: https://my.clockodo.com": "Your Clockodo email or API key is invalid. Find your API key under Personal data in Clockodo, then reconnect.",
            "403 Client Error: Forbidden for url: https://my.clockodo.com": "Your Clockodo user does not have permission to read this data. Clockodo credentials are scoped per co-worker — check the user's permissions, then reconnect.",
        }

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

        return CANONICAL_DESCRIPTIONS

    def get_schemas(
        self,
        config: ClockodoSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        endpoints = endpoints_for_version(self.resolve_api_version(api_version))
        # Clockodo exposes no server-side modified-since filter, so every table is full refresh only.
        return build_endpoint_schemas(
            ENDPOINTS,
            INCREMENTAL_FIELDS,
            names,
            descriptions={
                endpoint: config.description for endpoint, config in endpoints.items() if config.description is not None
            },
            should_sync_default={endpoint: config.should_sync_default for endpoint, config in endpoints.items()},
        )

    def validate_credentials(
        self,
        config: ClockodoSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        if validate_clockodo_credentials(config.api_user, config.api_key, self.resolve_api_version(api_version)):
            return True, None

        return False, "Invalid Clockodo credentials"

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

    def source_for_pipeline(
        self,
        config: ClockodoSourceConfig,
        resumable_source_manager: ResumableSourceManager[ClockodoResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        return clockodo_source(
            api_user=config.api_user,
            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,
            api_version=self.resolve_api_version(inputs.api_version),
        )

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.CLOCKODO,
            category=DataWarehouseSourceCategory.PRODUCTIVITY,
            label="Clockodo",
            releaseStatus=ReleaseStatus.BETA,
            caption="""Enter your Clockodo email and API key to pull your Clockodo time-tracking data into the PostHog Data warehouse.

You can find your personal API key under **Personal data** in your Clockodo account. Credentials are scoped to that co-worker's permissions, so connect a user that can see the data you want to sync.""",
            iconPath="/static/services/clockodo.png",
            docsUrl="https://posthog.com/docs/cdp/sources/clockodo",
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_user",
                        label="Email",
                        type=SourceFieldInputConfigType.EMAIL,
                        required=True,
                        placeholder="[email protected]",
                        secret=False,
                    ),
                    SourceFieldInputConfig(
                        name="api_key",
                        label="API key",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                ],
            ),
        )