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

from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceFieldSelectConfig,
    SourceFieldSelectConfigOption,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    WebhookCreationResult,
    WebhookDeletionResult,
    WebhookSource,
    WebhookSourceManager,
    build_endpoint_schemas,
    detect,
)
from products.warehouse_sources.sources.zapsign import zapsign as api_client
from products.warehouse_sources.sources.zapsign._config import ZapSignSourceConfig
from products.warehouse_sources.sources.zapsign.settings import DOCUMENTS_RESOURCE, ENDPOINTS, INCREMENTAL_FIELDS
from products.warehouse_sources.sources.zapsign.zapsign import ZapSignResumeConfig

if TYPE_CHECKING:
    from products.warehouse_sources.sources.sdk import HogFunctionTemplateDC


@SourceRegistry.register
class ZapSignSource(
    ResumableSource[ZapSignSourceConfig, ZapSignResumeConfig],
    WebhookSource[ZapSignSourceConfig],
):
    codebase_detection = detect(env=("^(ZAP_SIGN|ZAPSIGN)_",))

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

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

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        # ZapSign answers 403 (not 401) for a missing/invalid API token.
        return {
            "403 Client Error: Forbidden": (
                "ZapSign rejected the API token. Copy a valid token from "
                "Settings > Integrations > ZapSign API and reconnect."
            ),
            "401 Client Error: Unauthorized": (
                "ZapSign rejected the API token. Copy a valid token from "
                "Settings > Integrations > ZapSign API and reconnect."
            ),
        }

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

        return CANONICAL_DESCRIPTIONS

    @property
    def webhook_template(self) -> Optional["HogFunctionTemplateDC"]:
        from products.warehouse_sources.sources.zapsign.webhook_template import template

        return template

    @property
    def webhook_resource_map(self) -> dict[str, str]:
        # Every ZapSign document event routes to the single documents table, so the mapping is
        # keyed by the wildcard the Hog template looks up.
        return {DOCUMENTS_RESOURCE: "*"}

    def get_schemas(
        self,
        config: ZapSignSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        # Documents are merge-only: the created_from filter re-fetches the watermark's whole day,
        # so append mode would write duplicate rows.
        return build_endpoint_schemas(
            ENDPOINTS,
            INCREMENTAL_FIELDS,
            names,
            merge_only=(DOCUMENTS_RESOURCE,),
            supports_webhooks=(DOCUMENTS_RESOURCE,),
        )

    def validate_credentials(
        self,
        config: ZapSignSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        return api_client.validate_credentials(config.api_token, config.environment)

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

    def get_webhook_source_manager(self, inputs: SourceInputs) -> WebhookSourceManager:
        return WebhookSourceManager(inputs, inputs.logger)

    def create_webhook(
        self, config: ZapSignSourceConfig, webhook_url: str, team_id: int, api_version: str | None = None
    ) -> WebhookCreationResult:
        return api_client.create_webhook(config.api_token, config.environment, webhook_url)

    def delete_webhook(
        self, config: ZapSignSourceConfig, webhook_url: str, team_id: int, api_version: str | None = None
    ) -> WebhookDeletionResult:
        return api_client.delete_webhook()

    def source_for_pipeline(
        self,
        config: ZapSignSourceConfig,
        resumable_source_manager: ResumableSourceManager[ZapSignResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        return api_client.zapsign_source(
            api_token=config.api_token,
            environment=config.environment,
            endpoint=inputs.schema_name,
            team_id=inputs.team_id,
            job_id=inputs.job_id,
            resumable_source_manager=resumable_source_manager,
            webhook_source_manager=self.get_webhook_source_manager(inputs),
            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,
        )

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.ZAPSIGN,
            category=DataWarehouseSourceCategory.SALES,
            label="ZapSign",
            caption=(
                "Connect your ZapSign account using an API token to sync documents, signers, and "
                "templates. Find the token in ZapSign under **Settings** > **Integrations** > "
                "**ZapSign API**."
            ),
            keywords=["e-signature", "esignature", "digital signature"],
            iconPath="/static/services/zapsign.png",
            docsUrl="https://posthog.com/docs/cdp/sources/zapsign",
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_token",
                        label="API token",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                    SourceFieldSelectConfig(
                        name="environment",
                        label="Environment",
                        required=True,
                        defaultValue="production",
                        options=[
                            SourceFieldSelectConfigOption(label="Production (api.zapsign.com.br)", value="production"),
                            SourceFieldSelectConfigOption(
                                label="Sandbox (sandbox.api.zapsign.com.br)", value="sandbox"
                            ),
                        ],
                    ),
                ],
            ),
            releaseStatus=ReleaseStatus.BETA,
            webhookSetupCaption=(
                "PostHog tries to register a webhook in ZapSign using your API token, subscribed "
                "to all document events (created, signed, refused, deleted). The webhook "
                "authenticates itself with an **Authorization** header PostHog generates and "
                "verifies on every delivery.\n\n"
                "**Manual setup** (only needed if auto-registration failed):\n\n"
                "1. In ZapSign, go to **Settings** > **Integrations** > **ZapSign API** > **Webhooks**\n"
                "2. Paste the webhook URL shown below\n"
                "3. Add an **Authorization** header with a secret value you generate — paste the "
                "same value into the field below so PostHog can verify deliveries\n"
                "4. Subscribe to all document events\n\n"
                "ZapSign has no API to look up webhooks later, so if you disconnect this source, "
                "remove the webhook in ZapSign manually."
            ),
            webhookFields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="authorization_header",
                        label="Authorization header value",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="Bearer my-secret",
                        caption=(
                            "The exact value ZapSign will send in the Authorization header. "
                            "Must match what's configured on the ZapSign webhook."
                        ),
                        secret=True,
                    ),
                ],
            ),
        )