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

from products.warehouse_sources.sources.iterable._config import IterableSourceConfig
from products.warehouse_sources.sources.iterable.iterable import (
    IterableResumeConfig,
    iterable_source,
    validate_credentials as validate_iterable_credentials,
)
from products.warehouse_sources.sources.iterable.settings import (
    APPEND_ONLY_ENDPOINTS,
    ENDPOINTS,
    INCREMENTAL_FIELDS,
    SHOULD_SYNC_DEFAULT,
)
from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceFieldSelectConfig,
    SourceFieldSelectConfigOption,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    build_endpoint_schemas,
    detect,
)


@SourceRegistry.register
class IterableSource(ResumableSource[IterableSourceConfig, IterableResumeConfig]):
    codebase_detection = detect(
        env=("^ITERABLE_",),
        npm=("@iterable/web-sdk", "@iterable/react-native-sdk"),
        cocoapods=(
            "Iterable-iOS-SDK",
            "Iterable-iOS-AppExtensions",
            "Iterable-iOS-Inboxless-SDK",
            "IterableAppExtensions",
            "IterableSDK",
        ),
        maven=(
            "com.iterable:iterableapi",
            "com.iterable:iterableapi-ui",
            "com.iterable:iterableplayutils_2.10",
            "com.iterable:iterableplayutils_2.11",
            "com.iterable:iterableplayutils_2.12",
            "com.iterable:iterableplayutils_2.13",
        ),
        swiftpm=("github.com/iterable/iterable-swift-sdk",),
    )

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

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

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

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "401 Client Error": (
                "Iterable rejected the API key. Make sure you're using a server-side API key from the "
                "matching data center (US or EU) and reconnect."
            ),
            "403 Client Error": (
                "The Iterable API key doesn't have permission for this endpoint. Grant the key access to "
                "the resources you're syncing and reconnect."
            ),
        }

    def get_retryable_errors(self) -> set[str]:
        # `iterable.py` already retries 429s via the tracked session's RATE_LIMITED_RETRY (honoring
        # Retry-After, with the export/metrics-specific backoff) and paces export requests between
        # windows. If that budget still exhausts, Temporal retries the whole activity, so the
        # failure is self-recovering rather than a bug to page on.
        return {"429 Client Error"}

    def get_schemas(
        self,
        config: IterableSourceConfig,
        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,
            append_only=APPEND_ONLY_ENDPOINTS,
            should_sync_default=SHOULD_SYNC_DEFAULT,
        )

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

        return False, "Invalid Iterable API key for the selected data center"

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

    def source_for_pipeline(
        self,
        config: IterableSourceConfig,
        resumable_source_manager: ResumableSourceManager[IterableResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        return iterable_source(
            api_key=config.api_key,
            region=config.region,
            endpoint=inputs.schema_name,
            team_id=inputs.team_id,
            job_id=inputs.job_id,
            resumable_source_manager=resumable_source_manager,
            db_incremental_field_last_value=inputs.db_incremental_field_last_value
            if inputs.should_use_incremental_field
            else None,
        )

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.ITERABLE,
            category=DataWarehouseSourceCategory.MARKETING___EMAIL,
            label="Iterable",
            caption="""Enter your Iterable API key to pull your Iterable data into the PostHog Data warehouse.

Create a **server-side** API key with read permissions in your [Iterable integrations settings](https://app.iterable.com/settings/apiKeys). Client-side (Mobile/Browser/JWT) keys are not supported.

Make sure the data center below matches the one that issued your key (US or EU).""",
            iconPath="/static/services/iterable.png",
            docsUrl="https://posthog.com/docs/cdp/sources/iterable",
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_key",
                        label="API key",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                    SourceFieldSelectConfig(
                        name="region",
                        label="Data center",
                        required=True,
                        defaultValue="us",
                        options=[
                            SourceFieldSelectConfigOption(label="US (api.iterable.com)", value="us"),
                            SourceFieldSelectConfigOption(label="EU (api.eu.iterable.com)", value="eu"),
                        ],
                    ),
                ],
            ),
            releaseStatus=ReleaseStatus.GA,
        )