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

from products.warehouse_sources.sources.gitbook._config import GitBookSourceConfig
from products.warehouse_sources.sources.gitbook.gitbook import GitBookResumeConfig, gitbook_source, validate_credentials
from products.warehouse_sources.sources.gitbook.settings import ENDPOINTS, GITBOOK_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 GitBookSource(ResumableSource[GitBookSourceConfig, GitBookResumeConfig]):
    codebase_detection = detect(env=("^GITBOOK_",), npm=("@gitbook/api", "@gitbook/embed"))

    lists_tables_without_credentials = True  # static endpoint catalog — safe for public docs
    api_docs_url = "https://gitbook.com/docs/developers/gitbook-api/api-reference"

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

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.GITBOOK,
            category=DataWarehouseSourceCategory.PRODUCTIVITY,
            label="GitBook",
            releaseStatus=ReleaseStatus.GA,
            caption="""Enter your GitBook API token to pull your documentation workspace into the PostHog Data warehouse.

You can create a personal access token under **Account settings → Developer** in [GitBook](https://app.gitbook.com/account/developer). The token inherits your account permissions and grants read access to your organizations, spaces, pages, collections, sites, site questions and answers, members, teams, team members, change requests, and comments.
""",
            iconPath="/static/services/gitbook.png",
            docsUrl="https://posthog.com/docs/cdp/sources/gitbook",
            keywords=["docs", "documentation", "knowledge base", "wiki"],
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_token",
                        label="API token",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                ],
            ),
        )

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

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "401 Client Error: Unauthorized for url: https://api.gitbook.com": "Your GitBook API token is invalid or has been revoked. Generate a new token under Account settings → Developer, then reconnect.",
            "403 Client Error: Forbidden for url: https://api.gitbook.com": "Your GitBook API token does not have access to this data. Check the token owner's organization permissions, then reconnect.",
        }

    def get_schemas(
        self,
        config: GitBookSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        # Only `site_answers` has a server-side timestamp filter, so it is the only endpoint in
        # INCREMENTAL_FIELDS; every other endpoint is full refresh only.
        return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names)

    def validate_credentials(
        self,
        config: GitBookSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        # A single probe of `/user` confirms the token is genuine; per-endpoint access follows the
        # token owner's permissions and is surfaced at sync time via get_non_retryable_errors.
        return validate_credentials(config.api_token)

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

    def source_for_pipeline(
        self,
        config: GitBookSourceConfig,
        resumable_source_manager: ResumableSourceManager[GitBookResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        if inputs.schema_name not in GITBOOK_ENDPOINTS:
            raise ValueError(f"Unknown GitBook schema '{inputs.schema_name}'")

        return gitbook_source(
            api_token=config.api_token,
            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,
            incremental_field=inputs.incremental_field,
        )