: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
from typing import Optional, cast
from products.warehouse_sources.sources.plunk._config import PlunkSourceConfig
from products.warehouse_sources.sources.plunk.plunk import (
HOST_NOT_ALLOWED_ERROR,
HTTP_NOT_ALLOWED_ERROR,
PlunkResumeConfig,
plunk_source,
validate_credentials as validate_plunk_credentials,
)
from products.warehouse_sources.sources.plunk.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 PlunkSource(ResumableSource[PlunkSourceConfig, PlunkResumeConfig]):
codebase_detection = detect(env=("^PLUNK_", "^PLUNK_SECRET_KEY$"), npm=("@plunk/node",))
# Plunk's data endpoints carry no version prefix (only the public send/track endpoints
# are versioned), so the source is unversioned.
api_docs_url = "https://docs.useplunk.com/api-reference/overview"
lists_tables_without_credentials = True # static endpoint catalog — safe for public docs
@property
def source_type(self) -> ExternalDataSourceType:
return ExternalDataSourceType.PLUNK
@property
def connection_host_fields(self) -> list[str]:
# `base_url` is where the stored secret key is sent; retargeting it must re-require the key.
return ["base_url"]
def get_non_retryable_errors(self) -> dict[str, str | None]:
return {
"401 Client Error": "Invalid Plunk secret API key. Copy the sk_* key from your Plunk project settings and reconnect.",
"403 Client Error": "Plunk rejected the request. Check that your project is active and your account email is verified.",
HOST_NOT_ALLOWED_ERROR: "The Plunk API URL is not allowed. Please use a publicly reachable host.",
HTTP_NOT_ALLOWED_ERROR: "The Plunk API URL must use HTTPS. Please update the API URL to use https://.",
}
def get_canonical_descriptions(self) -> CanonicalDescriptions:
from products.warehouse_sources.sources.plunk.canonical_descriptions import ( # noqa: PLC0415
CANONICAL_DESCRIPTIONS,
)
return CANONICAL_DESCRIPTIONS
def get_schemas(
self,
config: PlunkSourceConfig,
team_id: int,
with_counts: bool = False,
names: list[str] | None = None,
force_refresh: bool = False,
api_version: str | None = None,
) -> list[SourceSchema]:
# No Plunk list endpoint accepts a server-side timestamp filter, so every
# endpoint is full-refresh only (INCREMENTAL_FIELDS is empty per endpoint).
return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names)
def validate_credentials(
self, config: PlunkSourceConfig, team_id: int, schema_name: Optional[str] = None, api_version: str | None = None
) -> tuple[bool, str | None]:
return validate_plunk_credentials(config.base_url, config.api_key, schema_name, team_id)
def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[PlunkResumeConfig]:
return ResumableSourceManager[PlunkResumeConfig](inputs, PlunkResumeConfig)
def source_for_pipeline(
self,
config: PlunkSourceConfig,
resumable_source_manager: ResumableSourceManager[PlunkResumeConfig],
inputs: SourceInputs,
) -> SourceResponse:
return plunk_source(
base_url=config.base_url,
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,
)
@property
def get_source_config(self) -> SourceConfig:
return SourceConfig(
name=ExternalDataSourceType.PLUNK,
category=DataWarehouseSourceCategory.MARKETING___EMAIL,
label="Plunk",
releaseStatus=ReleaseStatus.GA,
keywords=["useplunk", "email marketing"],
caption="""Enter your Plunk secret API key to pull your contacts, campaigns, templates, and segments into the PostHog Data warehouse.
You can find your secret API key (it starts with `sk_`) in your Plunk project settings under **Project Settings > API Keys**. The public key (`pk_`) cannot read data.
Self-hosted users should set the API URL to their own Plunk API host (for example `https://plunk-api.example.com`). Leave it blank to use the hosted Plunk (`https://next-api.useplunk.com`).""",
iconPath="/static/services/plunk.png",
docsUrl="https://posthog.com/docs/cdp/sources/plunk",
fields=cast(
list[FieldType],
[
SourceFieldInputConfig(
name="api_key",
label="Secret API key",
type=SourceFieldInputConfigType.PASSWORD,
required=True,
placeholder="sk_...",
secret=True,
),
SourceFieldInputConfig(
name="base_url",
label="API URL (self-hosted only)",
type=SourceFieldInputConfigType.TEXT,
required=False,
placeholder="https://next-api.useplunk.com",
secret=False,
),
],
),
)