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.

8.5 KB
Raw Blame
from typing import Optional, cast

from products.warehouse_sources.sources.bigcommerce._config import BigCommerceSourceConfig
from products.warehouse_sources.sources.bigcommerce.bigcommerce import (
    BigCommerceResumeConfig,
    bigcommerce_source,
    order_fan_out_source,
    validate_credentials as validate_bigcommerce_credentials,
)
from products.warehouse_sources.sources.bigcommerce.settings import (
    ENDPOINTS,
    INCREMENTAL_FIELDS,
    ORDER_FAN_OUT_ENDPOINTS,
    PARTITION_FIELDS,
    PRIMARY_KEYS,
)
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 BigCommerceSource(ResumableSource[BigCommerceSourceConfig, BigCommerceResumeConfig]):
    codebase_detection = detect(
        env=("^BIGCOMMERCE_",),
        script_hosts=("checkout-sdk.bigcommerce.com",),
        npm=(
            "node-bigcommerce",
            "@bigcommerce/checkout-sdk",
            "@bigcommerce/catalyst-client",
            "@bigcommerce/stencil-utils",
        ),
        pypi=("bigcommerce",),
        composer=("bigcommerce/api",),
        rubygems=("bigcommerce",),
    )

    lists_tables_without_credentials = True  # static endpoint catalog — safe for public docs
    supported_versions = ("v3",)
    default_version = "v3"
    api_docs_url = "https://developer.bigcommerce.com/api-reference"

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

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "401 Client Error": "BigCommerce authentication failed. Check your store hash and access token.",
            "403 Client Error": (
                "Your BigCommerce access token does not have the required OAuth scopes for this resource."
            ),
        }

    def get_canonical_descriptions(self) -> CanonicalDescriptions:
        from products.warehouse_sources.sources.bigcommerce.canonical_descriptions import (  # noqa: PLC0415 -- lazy import keeps this out of the hot registration path
            CANONICAL_DESCRIPTIONS,
        )

        return CANONICAL_DESCRIPTIONS

    def get_schemas(
        self,
        config: BigCommerceSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names)

    def validate_credentials(
        self,
        config: BigCommerceSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        if not config.store_hash or not config.access_token:
            return False, "Missing BigCommerce credentials"

        status = validate_bigcommerce_credentials(config.store_hash, config.access_token)

        if status == 200:
            return True, None

        # A token scoped to only some resources still passes the create-time probe; per-table
        # access is reported separately at sync time via get_non_retryable_errors.
        if status == 403 and schema_name is None:
            return True, None

        if status == 403:
            return False, "Your BigCommerce access token does not have the required OAuth scopes for this resource."

        if status == 401:
            return False, "BigCommerce authentication failed. Check your store hash and access token."

        return False, "Could not connect to your BigCommerce store. Please check the store hash."

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

    def source_for_pipeline(
        self,
        config: BigCommerceSourceConfig,
        resumable_source_manager: ResumableSourceManager[BigCommerceResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        # Only the endpoints that expose a server-side "modified since" filter sync
        # incrementally — guard against a stale schema requesting it elsewhere.
        use_incremental = inputs.should_use_incremental_field and inputs.schema_name in INCREMENTAL_FIELDS

        if inputs.schema_name in ORDER_FAN_OUT_ENDPOINTS:
            response = SourceResponse(
                name=inputs.schema_name,
                items=lambda: order_fan_out_source(
                    config.store_hash, config.access_token, inputs.schema_name, resumable_source_manager
                ),
                primary_keys=PRIMARY_KEYS[inputs.schema_name],
                sort_mode="asc",
            )
            self._set_partitioning(response, inputs.schema_name)
            return response

        resource = bigcommerce_source(
            store_hash=config.store_hash,
            access_token=config.access_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=use_incremental,
            db_incremental_field_last_value=inputs.db_incremental_field_last_value if use_incremental else None,
        )

        response = SourceResponse(
            name=resource.name,
            items=lambda: resource,
            primary_keys=PRIMARY_KEYS.get(inputs.schema_name, ["id"]),
            column_hints=resource.column_hints,
            # Whether BigCommerce's `sort`/`direction` params hold a stable ascending order
            # page-to-page isn't verified against a live store. Deferring the watermark commit
            # until the whole resource has been read (desc semantics) avoids skipping rows if
            # the true order turns out not to be strictly ascending.
            sort_mode="desc" if use_incremental else "asc",
        )

        self._set_partitioning(response, inputs.schema_name)
        return response

    @staticmethod
    def _set_partitioning(response: SourceResponse, schema_name: str) -> None:
        partition_key = PARTITION_FIELDS.get(schema_name)
        if partition_key:
            response.partition_count = 1
            response.partition_size = 1
            response.partition_mode = "datetime"
            response.partition_format = "month"
            response.partition_keys = [partition_key]

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.BIGCOMMERCE,
            category=DataWarehouseSourceCategory.E_COMMERCE,
            label="BigCommerce",
            caption=(
                "Enter your BigCommerce store hash and API access token to pull your store data into "
                "the PostHog Data warehouse. Create an API account under **Settings → API → "
                "Store-level API accounts** with `read-only` scope for **Products**, **Orders** and "
                "**Customers**. To sync channels and order transactions, also grant `read-only` scope for "
                "**Channel Settings** and **Order Transactions**."
            ),
            iconPath="/static/services/bigcommerce.png",
            docsUrl="https://posthog.com/docs/cdp/sources/bigcommerce",
            releaseStatus=ReleaseStatus.GA,
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="store_hash",
                        label="Store hash",
                        type=SourceFieldInputConfigType.TEXT,
                        required=True,
                        placeholder="abc123",
                        secret=False,
                        caption="Found in your store's control panel URL: `https://store-{store_hash}.mybigcommerce.com`.",
                    ),
                    SourceFieldInputConfig(
                        name="access_token",
                        label="Access token",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                ],
            ),
        )