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.

14.6 KB
Raw Blame
from datetime import datetime
from typing import Any, Literal

from django.db.models import Q, QuerySet

from rest_framework import filters, serializers, viewsets

from posthog.api.forbid_destroy_model import ForbidDestroyModel
from posthog.api.pagination import BoundedLimitOffsetPagination
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.scoped_related_fields import TeamScopedPrimaryKeyRelatedField
from posthog.api.shared import UserBasicSerializer
from posthog.models.user import User
from posthog.models.utils import strict_fetch

from products.annotations.backend.models.annotation import Annotation
from products.dashboards.backend.models.dashboard import Dashboard
from products.product_analytics.backend.facade.models import Insight


class AnnotationSerializer(serializers.ModelSerializer):
    created_by = UserBasicSerializer(read_only=True)
    # Soft-deleted parents resolve here because the frontend echoes both FKs back on every write. A
    # project-scoped annotation whose dashboard was deleted would otherwise be impossible to edit or
    # delete. Only the pointer the annotation already stores may be echoed. Every other deleted
    # parent answers as if it does not exist. validate() then rejects a write whose own scope points
    # at a soft-deleted parent.
    dashboard_id = serializers.IntegerField(
        required=False,
        allow_null=True,
        help_text="Optional dashboard ID to attach this annotation to. Must belong to the current project.",
    )
    dashboard_item = TeamScopedPrimaryKeyRelatedField(
        queryset=Insight.objects_including_soft_deleted.all(),
        required=False,
        allow_null=True,
        help_text="Optional insight ID to attach this annotation to. Must belong to the current project.",
    )

    class Meta:
        model = Annotation
        fields = [
            "id",
            "content",
            "date_marker",
            "creation_type",
            "dashboard_item",
            "dashboard_id",
            "dashboard_name",
            "insight_short_id",
            "insight_name",
            "insight_derived_name",
            "created_by",
            "created_at",
            "updated_at",
            "deleted",
            "scope",
            "emoji",
            "hidden_in_user_interface",
        ]
        read_only_fields = [
            "id",
            "insight_short_id",
            "insight_name",
            "insight_derived_name",
            "dashboard_name",
            "created_by",
            "created_at",
            "updated_at",
        ]
        extra_kwargs = {
            "content": {
                "help_text": "Annotation text shown on charts to describe the change, release, or incident.",
            },
            "date_marker": {
                "help_text": "When this annotation happened (ISO 8601 timestamp). Used to position it on charts.",
            },
            "creation_type": {
                "help_text": "Who created this annotation. Use `USR` for user-created notes and `GIT` for bot/deployment notes.",
            },
            "deleted": {
                "help_text": "Soft-delete flag. Set to true to hide the annotation, or false to restore it.",
            },
            "scope": {
                "help_text": (
                    "Annotation visibility scope: `project`, `organization`, `dashboard`, or `dashboard_item`. "
                    "`recording` is deprecated and rejected."
                ),
            },
            "emoji": {
                "help_text": "Optional emoji shown in place of the default badge when this annotation is surfaced on a chart.",
                "required": False,
                "allow_null": True,
                "allow_blank": True,
            },
            "hidden_in_user_interface": {
                "help_text": (
                    "When true, the annotation is hidden from the PostHog UI (charts and the annotations list) "
                    "but still readable over the API and MCP. Use for high-frequency markers like deployments "
                    "that would otherwise crowd the UI. Null (the default) means the annotation is shown."
                ),
                "required": False,
                "allow_null": True,
            },
        }

    def validate_emoji(self, value: str | None) -> str | None:
        # Normalise blank strings to None so the DB has a single canonical "no emoji" state.
        return value or None

    def validate_dashboard_item(self, value: Insight | None) -> Insight | None:
        # A deleted insight answers exactly as an unknown one does unless the annotation already
        # points at it, so a guessed ID cannot report back its name.
        if value is not None and value.deleted and value.pk != getattr(self.instance, "dashboard_item_id", None):
            self.fields["dashboard_item"].fail("does_not_exist", pk_value=value.pk)
        return value

    def update(self, instance: Annotation, validated_data: dict[str, Any]) -> Annotation:
        instance.team_id = self.context["team_id"]
        return super().update(instance, validated_data)

    def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
        team = self.context["get_team"]()

        scope = attrs.get("scope", None)
        if scope == Annotation.Scope.RECORDING.value:
            raise serializers.ValidationError("Recording scope is deprecated")

        # Resolve the parents the annotation will have after this write. A key absent from `attrs`
        # keeps the stored value, while a key present but null clears it, so membership is what
        # distinguishes the two on a PATCH.
        dashboard = None
        if "dashboard_id" in attrs:
            if attrs["dashboard_id"] is not None:
                dashboard = Dashboard.objects_including_soft_deleted.filter(
                    id=attrs["dashboard_id"], team_id=team.id
                ).first()
                # A deleted dashboard answers exactly as an unknown one does unless the annotation
                # already points at it, so a guessed ID cannot report back its name.
                if dashboard is None or (
                    dashboard.deleted and dashboard.id != getattr(self.instance, "dashboard_id", None)
                ):
                    raise serializers.ValidationError({"dashboard_id": "Dashboard not found."})
                if dashboard.id != getattr(self.instance, "dashboard_id", None):
                    self._require_viewer_access(dashboard, "dashboard_id", "dashboard")
        elif self.instance is not None:
            dashboard = self.instance.dashboard

        if "dashboard_item" in attrs:
            insight = attrs["dashboard_item"]
            if insight is not None and insight.pk != getattr(self.instance, "dashboard_item_id", None):
                self._require_viewer_access(insight, "dashboard_item", "insight")
        else:
            insight = getattr(self.instance, "dashboard_item", None)

        # A create checks only an explicit scope, because rows created without one take the model
        # default and have no insight. An update checks the scope the row will have, so clearing the
        # parent is caught too. A row already stored without its parent, such as a default row or one
        # whose dashboard was hard-deleted, stays editable, because the UI echoes its scope back.
        instance = self.instance
        checked_scope = scope if instance is None else scope or instance.scope
        if (
            checked_scope == Annotation.Scope.INSIGHT.value
            and insight is None
            and not (instance is not None and instance.scope == checked_scope and instance.dashboard_item_id is None)
        ):
            raise serializers.ValidationError(
                {"dashboard_item": "Set `dashboard_item` to the insight ID when the scope is `dashboard_item`."}
            )
        if (
            checked_scope == Annotation.Scope.DASHBOARD.value
            and dashboard is None
            and not (instance is not None and instance.scope == checked_scope and instance.dashboard_id is None)
        ):
            raise serializers.ValidationError(
                {"dashboard_id": "Set `dashboard_id` to the dashboard ID when the scope is `dashboard`."}
            )

        # AnnotationsViewSet.safely_get_queryset hides an annotation whose own scope points at a
        # soft-deleted parent, so accepting one here would strand a row that nothing can list, edit
        # or delete. Project- and organization-scoped rows keep their pointers, which are only used
        # to show where the annotation was created.
        effective_scope = scope or getattr(self.instance, "scope", Annotation.Scope.INSIGHT.value)
        if effective_scope == Annotation.Scope.INSIGHT.value and insight is not None and insight.deleted:
            raise serializers.ValidationError(
                {"dashboard_item": "This insight is deleted. Restore it, or pick a different scope."}
            )
        if effective_scope == Annotation.Scope.DASHBOARD.value and dashboard is not None and dashboard.deleted:
            raise serializers.ValidationError(
                {"dashboard_id": "This dashboard is deleted. Restore it, or pick a different scope."}
            )

        return attrs

    def _require_viewer_access(
        self, parent: Dashboard | Insight, field: str, resource: Literal["dashboard", "insight"]
    ) -> None:
        user_access_control = self.context["view"].user_access_control
        if isinstance(self.context["request"].user, User) and user_access_control.denied_object_ids(
            resource, [(str(parent.pk), parent.team_id, parent.created_by_id)], "viewer"
        ):
            raise serializers.ValidationError({field: f"You need viewer access to this {resource} to annotate it."})

    def create(self, validated_data: dict[str, Any], *args: Any, **kwargs: Any) -> Annotation:
        request = self.context["request"]
        team = self.context["get_team"]()

        annotation = Annotation.objects.create(
            organization_id=team.organization_id,
            team_id=team.id,
            created_by=request.user,
            **validated_data,
        )
        return annotation


class AnnotationsLimitOffsetPagination(BoundedLimitOffsetPagination):
    default_limit = 1000


class AnnotationsViewSet(TeamAndOrgViewSetMixin, ForbidDestroyModel, viewsets.ModelViewSet):
    """
    Create, Read, Update and Delete annotations. [See docs](https://posthog.com/docs/data/annotations) for more information on annotations.
    """

    scope_object = "annotation"
    queryset = (
        Annotation.objects.select_related("dashboard_item").select_related("dashboard").select_related("created_by")
    )
    serializer_class = AnnotationSerializer
    filter_backends = [filters.SearchFilter]
    pagination_class = AnnotationsLimitOffsetPagination
    search_fields = ["content"]

    def safely_get_queryset(self, queryset) -> QuerySet:
        if self.action == "list":
            # `date_marker` alone is not a total order, so limit-offset pages can repeat or drop rows.
            queryset = strict_fetch(queryset.order_by("-date_marker", "-id"))
        if self.action != "partial_update":
            # We never want deleted items to be included in the queryset… except when we want to restore an annotation
            # That's because annotations are restored with a PATCH request setting `deleted` to `False`
            queryset = queryset.filter(deleted=False)
        # Annotations scoped to a soft-deleted insight or dashboard are hidden
        # across all actions, including `partial_update`, so they cannot be
        # individually edited or restored while their parent is soft-deleted.
        # They reappear automatically when the parent is restored. Mirrors how
        # alerts behave (see posthog/temporal/alerts/activities.py).
        # Gated on scope: every annotation records the insight and dashboard it was
        # created from, so a project- or organization-scoped one would otherwise
        # disappear project-wide once that parent is deleted.
        queryset = queryset.exclude(scope=Annotation.Scope.INSIGHT, dashboard_item__deleted=True).exclude(
            scope=Annotation.Scope.DASHBOARD, dashboard__deleted=True
        )

        scope = self.request.query_params.get("scope")
        if scope:
            # let's allow the more recently used "insight" scope to be used as "dashboard_item"
            scope = "dashboard_item" if scope == "insight" else scope
            if scope not in [scope.value for scope in Annotation.Scope]:
                raise serializers.ValidationError(f"Invalid scope: {scope}")

            queryset = queryset.filter(scope=scope)

        # Add date range filtering
        date_from = self.request.query_params.get("date_from")
        date_to = self.request.query_params.get("date_to")

        date_from_parsed = None
        date_to_parsed = None

        if date_from:
            try:
                date_from_parsed = datetime.fromisoformat(date_from.replace("Z", "+00:00"))
                queryset = queryset.filter(date_marker__gte=date_from_parsed)
            except ValueError:
                raise serializers.ValidationError("Invalid date range: date_from must be a valid ISO 8601 date")

        if date_to:
            try:
                date_to_parsed = datetime.fromisoformat(date_to.replace("Z", "+00:00"))
                queryset = queryset.filter(date_marker__lte=date_to_parsed)
            except ValueError:
                raise serializers.ValidationError("Invalid date range: date_to must be a valid ISO 8601 date")

        if date_from_parsed and date_to_parsed and date_from_parsed > date_to_parsed:
            raise serializers.ValidationError("Invalid date range: date_from must be before date_to")

        # Add is_emoji filtering
        is_emoji = self.request.query_params.get("is_emoji")
        if is_emoji is not None:
            # Convert string to boolean (true, 1, yes -> True; false, 0, no -> False)
            is_emoji_bool = is_emoji.lower() in ("true", "1", "yes")
            queryset = queryset.filter(is_emoji=is_emoji_bool)

        hidden_in_user_interface = self.request.query_params.get("hidden_in_user_interface")
        if hidden_in_user_interface is not None:
            if hidden_in_user_interface.lower() in ("true", "1", "yes"):
                queryset = queryset.filter(hidden_in_user_interface=True)
            else:
                queryset = queryset.filter(Q(hidden_in_user_interface=False) | Q(hidden_in_user_interface__isnull=True))

        return queryset

    def _filter_queryset_by_parents_lookups(self, queryset):
        team = self.team
        return queryset.filter(
            Q(scope=Annotation.Scope.ORGANIZATION, organization_id=team.organization_id) | Q(team=team)
        )