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.

5.2 KB
Raw Blame
from typing import Optional, cast

from products.warehouse_sources.sources.clockify._config import ClockifySourceConfig
from products.warehouse_sources.sources.clockify.clockify import (
    ClockifyResumeConfig,
    clockify_source,
    validate_credentials as validate_clockify_credentials,
)
from products.warehouse_sources.sources.clockify.settings import ENDPOINTS, INCREMENTAL_FIELDS
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,
)


@SourceRegistry.register
class ClockifySource(ResumableSource[ClockifySourceConfig, ClockifyResumeConfig]):
    codebase_detection = detect(env=("^CLOCKIFY_",))

    api_docs_url = "https://docs.clockify.me"

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

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.CLOCKIFY,
            category=DataWarehouseSourceCategory.PRODUCTIVITY,
            label="Clockify",
            releaseStatus=ReleaseStatus.BETA,
            caption="""Enter your Clockify API key to sync your Clockify data into the PostHog Data warehouse.

You can generate an API key on your [Clockify profile settings](https://app.clockify.me/user/settings) page.

The key is user-scoped — it can read exactly what your Clockify user can. Use an admin or owner key to sync workspace-wide data (projects, clients, every member's time entries).""",
            iconPath="/static/services/clockify.png",
            docsUrl="https://posthog.com/docs/cdp/sources/clockify",
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_key",
                        label="API key",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                ],
            ),
        )

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        # An invalid/revoked key surfaces as a requests HTTPError when `_fetch_page` calls
        # `raise_for_status()`. Match the stable status text and base host, not the per-request
        # path/query. Clockify keys carry no per-endpoint scopes, so a 403 is a credential problem
        # too (e.g. a non-admin key reaching workspace-wide data).
        return {
            "401 Client Error: Unauthorized for url: https://api.clockify.me": "Your Clockify API key is invalid or has been revoked. Generate a new key in your Clockify profile settings, then reconnect.",
            "403 Client Error: Forbidden for url: https://api.clockify.me": "Your Clockify API key lacks the permissions needed to sync this data. Use an admin or owner key, then reconnect.",
        }

    def get_canonical_descriptions(self) -> CanonicalDescriptions:
        from products.warehouse_sources.sources.clockify.canonical_descriptions import (
            CANONICAL_DESCRIPTIONS,  # noqa: PLC0415
        )

        return CANONICAL_DESCRIPTIONS

    def get_schemas(
        self,
        config: ClockifySourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        # Only time_entries has a server-side timestamp filter; everything else is full refresh.
        return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names)

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

        return (
            False,
            "Your Clockify API key is invalid or has been revoked. Generate a new key in your Clockify profile settings, then reconnect.",
        )

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

    def source_for_pipeline(
        self,
        config: ClockifySourceConfig,
        resumable_source_manager: ResumableSourceManager[ClockifyResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        return clockify_source(
            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,
        )