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.

10.3 KB
Raw Blame
from typing import TYPE_CHECKING

from django.utils import timezone

import posthoganalytics
from drf_spectacular.extensions import OpenApiSerializerExtension
from rest_framework import serializers

from posthog.api.object_media_preview import visible_previews, with_preview_media
from posthog.api.shared import UserBasicSerializer
from posthog.api.tagged_item import TaggedItemSerializerMixin
from posthog.event_usage import groups
from posthog.models import ObjectMediaPreview
from posthog.models.organization import OrganizationMembership

from products.event_definitions.backend.models import EventDefinition

from ee.models.event_definition import EnterpriseEventDefinition

if TYPE_CHECKING:
    from drf_spectacular.openapi import AutoSchema
    from drf_spectacular.utils import Direction


class EnterpriseEventDefinitionSerializerExtension(OpenApiSerializerExtension):
    """Documents `owner` as a user ID in request bodies, and as the user object that `to_representation` returns."""

    target_class = "ee.api.ee_event_definition.EnterpriseEventDefinitionSerializer"

    def get_name(self, auto_schema: "AutoSchema", direction: "Direction") -> str | None:
        # One component cannot describe both `owner` shapes. A PATCH body already gets its own "Patched"
        # component, so only POST and PUT bodies need a name apart from the response.
        if direction == "request" and not getattr(self.target, "partial", False):
            return "EnterpriseEventDefinitionRequest"
        return None

    def map_serializer(self, auto_schema: "AutoSchema", direction: "Direction") -> dict[str, object]:
        schema: dict = auto_schema._map_serializer(self.target, direction, bypass_extensions=True)
        if direction == "response":
            schema["properties"]["owner"] = {
                "oneOf": [auto_schema.resolve_serializer(UserBasicSerializer, direction).ref, {"type": "null"}],
                "readOnly": True,
                "description": "The user responsible for the event, or null when it has no owner.",
            }
        return schema


class EnterpriseEventDefinitionSerializer(TaggedItemSerializerMixin, serializers.ModelSerializer):
    updated_by = UserBasicSerializer(read_only=True)
    verified_by = UserBasicSerializer(read_only=True)
    created_by = UserBasicSerializer(read_only=True)
    is_action = serializers.SerializerMethodField(read_only=True)
    action_id = serializers.IntegerField(read_only=True)
    is_calculating = serializers.BooleanField(read_only=True)
    last_calculated_at = serializers.DateTimeField(read_only=True)
    last_updated_at = serializers.DateTimeField(read_only=True)
    post_to_slack = serializers.BooleanField(default=False)
    default_columns = serializers.ListField(child=serializers.CharField(), required=False)
    media_preview_urls = serializers.SerializerMethodField(read_only=True)
    primary_property = serializers.CharField(
        required=False,
        allow_null=True,
        allow_blank=False,
        max_length=400,
        help_text=(
            "Name of a single property on this event that PostHog UIs should display alongside the event "
            "(for example `$pathname` on `$pageview`). When set, surfaces like the session replay inspector "
            "show the property's value next to the event name without the user having to open the event."
        ),
    )

    class Meta:
        model = EnterpriseEventDefinition
        fields = (
            "id",
            "name",
            "owner",
            "description",
            "tags",
            "created_at",
            "updated_at",
            "updated_by",
            "last_seen_at",
            "last_updated_at",
            "verified",
            "verified_at",
            "verified_by",
            "hidden",
            "enforcement_mode",
            "primary_property",
            # Action fields
            "is_action",
            "action_id",
            "is_calculating",
            "last_calculated_at",
            "created_by",
            "post_to_slack",
            "default_columns",
            "media_preview_urls",
        )
        extra_kwargs = {"owner": {"help_text": "ID of the user responsible for the event. Null removes the owner."}}
        read_only_fields = [
            "id",
            "name",
            "created_at",
            "updated_at",
            "last_seen_at",
            "last_updated_at",
            "verified_at",
            "verified_by",
            # Action fields
            "is_action",
            "action_id",
            "is_calculating",
            "last_calculated_at",
            "created_by",
        ]

    def get_extra_kwargs(self):
        extra_kwargs = super().get_extra_kwargs()

        # Allow name to be writable during creation, read-only during updates
        if self.instance is None:  # Creation
            extra_kwargs["name"] = {"read_only": False}

        return extra_kwargs

    def validate_owner(self, value):
        if value is None:
            return value
        view = self.context.get("view")
        organization_id = getattr(view, "organization_id", None) if view else None
        if organization_id is None:
            raise serializers.ValidationError("Cannot assign owner without organization context")
        if not OrganizationMembership.objects.filter(organization_id=organization_id, user=value).exists():
            raise serializers.ValidationError("Owner must be a member of this organization")
        return value

    def validate_name(self, value):
        # For creation, check if event definition with this name already exists
        if self.instance:
            return value

        view = self.context.get("view")
        if not view:
            return value

        if EventDefinition.objects.filter(team_id=view.team_id, name=value).exists():
            raise serializers.ValidationError(f"Event definition with name '{value}' already exists")

        return value

    def validate(self, data):
        validated_data = super().validate(data)

        # Validate mutual exclusion
        if "hidden" in validated_data and "verified" in validated_data:
            if validated_data["hidden"] and validated_data["verified"]:
                raise serializers.ValidationError("An event cannot be both hidden and verified")

        if validated_data.get("enforcement_mode") == "reject":
            request = self.context.get("request")
            if not request or not request.user:
                raise serializers.ValidationError(
                    'Setting schema enforcement mode to "reject" requires an authenticated request'
                )
            user = request.user
            org = getattr(user, "organization", None)
            org_id = str(org.id) if org else ""
            flag_enabled = posthoganalytics.feature_enabled(
                "schema-enforcement-reject",
                str(user.distinct_id),
                groups={"organization": org_id},
                group_properties={"organization": {"id": org_id}},
                only_evaluate_locally=False,
            )
            if not flag_enabled:
                raise serializers.ValidationError(
                    'Setting schema enforcement mode to "reject" requires the schema-enforcement-reject feature flag'
                )

        # Set verified metadata when verifying
        if "verified" in validated_data:
            user = self.context["request"].user
            if validated_data["verified"]:
                # Setting verified=True - only update metadata if not already verified (for updates)
                if self.instance is None or not self.instance.verified:
                    validated_data["verified_by"] = user
                    validated_data["verified_at"] = timezone.now()
                validated_data["hidden"] = False
            else:
                # Setting verified=False (unverifying)
                validated_data["verified_by"] = None
                validated_data["verified_at"] = None

        # Clear verified metadata when hiding
        if validated_data.get("hidden", False):
            validated_data["verified"] = False
            validated_data["verified_by"] = None
            validated_data["verified_at"] = None

        # Remove post_to_slack field - it exists on Action model but not EventDefinition
        validated_data.pop("post_to_slack", None)

        return validated_data

    def update(self, event_definition: EnterpriseEventDefinition, validated_data):
        """Track analytics for verification toggle."""
        user = self.context["request"].user

        # Track verification status changes for analytics
        if "verified" in validated_data:
            verified_old = event_definition.verified
            verified_new = validated_data["verified"]
            if verified_old != verified_new:
                posthoganalytics.capture(
                    "event verification toggled",
                    distinct_id=str(user.distinct_id),
                    properties={
                        "verified": verified_new,
                        "event_name": event_definition.name,
                        "is_custom_event": not event_definition.name.startswith("$"),
                    },
                    groups=groups(user.organization),
                )

        return super().update(event_definition, validated_data)

    def to_representation(self, instance):
        representation = super().to_representation(instance)
        representation["owner"] = (
            UserBasicSerializer(instance=instance.owner).data if hasattr(instance, "owner") and instance.owner else None
        )

        # Ensure default_columns is always an array
        if representation.get("default_columns") is None:
            representation["default_columns"] = []

        return representation

    def get_is_action(self, obj) -> bool:
        return hasattr(obj, "action_id") and obj.action_id is not None

    def get_media_preview_urls(self, obj) -> list[str]:
        media_map = self.context.get("media_preview_urls_map")
        if media_map is not None:
            return media_map.get(str(obj.id), [])

        if not obj.id:
            return []
        previews = with_preview_media(ObjectMediaPreview.objects.filter(event_definition_id=obj.id)).order_by(
            "-updated_at"
        )
        return [p.media_url for p in visible_previews(previews, self.context.get("view")) if p.media_url]