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

from products.warehouse_sources.sources.easypost._config import EasypostSourceConfig
from products.warehouse_sources.sources.easypost.easypost import (
    EasypostResumeConfig,
    easypost_source,
    validate_credentials as validate_easypost_credentials,
)
from products.warehouse_sources.sources.easypost.settings import EASYPOST_ENDPOINTS, ENDPOINTS, INCREMENTAL_FIELDS
from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    detect,
)


@SourceRegistry.register
class EasypostSource(ResumableSource[EasypostSourceConfig, EasypostResumeConfig]):
    codebase_detection = detect(
        env=("^EASYPOST_",),
        npm=("@easypost/api",),
        pypi=("easypost",),
        composer=("easypost/easypost-php",),
        go=("github.com/EasyPost/easypost-go",),
        maven=("com.easypost:easypost-api-client",),
        rubygems=("easypost",),
    )

    supported_versions = ("v2",)
    default_version = "v2"
    api_docs_url = "https://docs.easypost.com"

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

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.EASYPOST,
            category=DataWarehouseSourceCategory.E_COMMERCE,
            label="EasyPost",
            releaseStatus=ReleaseStatus.BETA,
            caption="""Enter your EasyPost API key to automatically pull your EasyPost shipping data into the PostHog Data warehouse.

You can find your API keys in your [EasyPost account settings](https://www.easypost.com/account/api-keys). Use a production key to sync production data, or a test key to sync test-mode data.""",
            iconPath="/static/services/easypost.png",
            docsUrl="https://posthog.com/docs/cdp/sources/easypost",
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_key",
                        label="API key",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="EZAK... or EZTK...",
                        secret=True,
                    ),
                ],
            ),
        )

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

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            # EasyPost API keys carry full account access (no per-endpoint scopes), so a 401 or 403
            # from a list endpoint means the key is invalid, revoked, or inactive — retrying can't
            # fix that. Match the stable status text and base host, not the per-request path.
            "401 Client Error: Unauthorized for url: https://api.easypost.com": "Your EasyPost API key is invalid or has been revoked. Create a new key in your EasyPost account settings, then reconnect.",
            "403 Client Error: Forbidden for url: https://api.easypost.com": "Your EasyPost API key is inactive or not authorized. Activate the key (or create a new one) in your EasyPost account settings, then reconnect.",
        }

    def get_schemas(
        self,
        config: EasypostSourceConfig,
        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 = EASYPOST_ENDPOINTS[endpoint]
            fields = INCREMENTAL_FIELDS.get(endpoint, [])
            return SourceSchema(
                name=endpoint,
                # `created_at` incremental sync appends newly created rows; immutable resources
                # (events) are append-only, mutable ones additionally allow incremental. The
                # lookup endpoints advertise no cursor field, so they are full refresh only.
                supports_incremental=bool(fields) and not endpoint_config.append_only,
                supports_append=bool(fields),
                incremental_fields=fields,
                should_sync_default=endpoint_config.should_sync_default,
            )

        schemas = [_build_schema(endpoint) for endpoint in 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: EasypostSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        if validate_easypost_credentials(config.api_key):
            return True, None

        return False, "Invalid EasyPost API key"

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

    def source_for_pipeline(
        self,
        config: EasypostSourceConfig,
        resumable_source_manager: ResumableSourceManager[EasypostResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        return easypost_source(
            api_key=config.api_key,
            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,
            incremental_field=inputs.incremental_field,
        )