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.5 KB
Raw Blame
from typing import Any

from django.db.models import QuerySet

import structlog
from drf_spectacular.utils import OpenApiParameter, extend_schema, extend_schema_field, extend_schema_view
from rest_framework import serializers, viewsets
from rest_framework.exceptions import ValidationError
from rest_framework.permissions import IsAuthenticated

from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.shared import UserBasicSerializer
from posthog.models.team.team import Team

from products.field_notes.backend.models import FieldNote

logger = structlog.get_logger(__name__)


@extend_schema_field(
    {
        "type": "object",
        "nullable": True,
        "properties": {
            "width": {"type": "integer", "description": "Viewport width in pixels."},
            "height": {"type": "integer", "description": "Viewport height in pixels."},
        },
    }
)
class ViewportField(serializers.JSONField):
    pass


@extend_schema_field(
    {
        "type": "object",
        "description": "Structured element metadata: inferred selectors, attributes, and component hints.",
        "additionalProperties": True,
    }
)
class ElementContextField(serializers.JSONField):
    pass


class FieldNoteSerializer(serializers.ModelSerializer):
    created_by = UserBasicSerializer(read_only=True)
    # Length caps on free-text fields — the toolbar runs on untrusted customer pages, so cap
    # what it can POST to keep rows (and downstream MCP payloads) bounded.
    comment = serializers.CharField(max_length=5000, help_text="The note the user wrote about the element.")
    url = serializers.CharField(max_length=2048, help_text="Full URL of the page the field note was made on.")
    host = serializers.CharField(max_length=255, help_text="Hostname of the page, used to scope field notes to a site.")
    pathname = serializers.CharField(
        max_length=2048, required=False, allow_null=True, allow_blank=True, help_text="Path portion of the URL."
    )
    selector = serializers.CharField(max_length=4096, help_text="CSS selector that locates the element on the page.")
    element_text = serializers.CharField(
        max_length=2048,
        required=False,
        allow_null=True,
        allow_blank=True,
        help_text="Visible text of the element, if any.",
    )
    element_chain = serializers.CharField(
        max_length=20000,
        required=False,
        allow_null=True,
        allow_blank=True,
        help_text="Serialized autocapture-style element chain from the element up to the document root.",
    )
    field_note_status = serializers.ChoiceField(
        choices=FieldNote.Status.choices,
        required=False,
        help_text="Lifecycle of the field note: pending, acknowledged, resolved, or dismissed. Ignored on create.",
    )
    screenshot_url = serializers.CharField(
        max_length=2048,
        required=False,
        allow_null=True,
        allow_blank=True,
        help_text="URL of an uploaded screenshot captured with the field_note.",
    )
    element_context = ElementContextField(
        required=False, help_text="Structured element metadata (inferred selectors, attributes, component hints)."
    )
    viewport = ViewportField(
        required=False, allow_null=True, help_text="Viewport size when the field note was made, as {width, height}."
    )

    class Meta:
        model = FieldNote
        fields = [
            "id",
            "comment",
            "field_note_status",
            "resolution",
            "url",
            "host",
            "pathname",
            "selector",
            "element_text",
            "element_chain",
            "element_context",
            "viewport",
            "screenshot_url",
            "created_at",
            "updated_at",
            "created_by",
        ]
        read_only_fields = ["id", "created_at", "updated_at", "created_by"]

    def create(self, validated_data: dict[str, Any]) -> FieldNote:
        team = Team.objects.get(id=self.context["team_id"])
        request = self.context["request"]
        # Field notes are always born `pending`; status/resolution are agent-only and only
        # settable via update — strip them so a write-scoped toolbar token can't forge a
        # pre-resolved field note with a fabricated resolution note.
        validated_data.pop("field_note_status", None)
        validated_data.pop("resolution", None)
        field_note = FieldNote.objects.create(
            team=team,
            created_by=request.user if request.user.is_authenticated else None,
            **validated_data,
        )
        logger.info("field_note_created", id=field_note.id, team_id=team.id, host=field_note.host)
        return field_note


@extend_schema_view(
    list=extend_schema(
        parameters=[
            OpenApiParameter(
                "field_note_status",
                type=str,
                enum=FieldNote.Status.values,
                required=False,
                description="Filter to field notes in this lifecycle state (e.g. `pending` for unaddressed feedback).",
            ),
            OpenApiParameter(
                "host",
                type=str,
                required=False,
                description="Filter to field notes made on this hostname (e.g. `app.example.com`).",
            ),
        ]
    )
)
class FieldNoteViewSet(TeamAndOrgViewSetMixin, viewsets.ModelViewSet):
    """
    Create, read, update, and resolve toolbar field notes — UI feedback a user
    points at on their own site, surfaced to coding agents over MCP.
    """

    scope_object = "field_note"
    # `.unscoped()` avoids the fail-closed manager raising at import (no team context yet);
    # `safely_get_queryset` re-scopes every real query to the team.
    queryset = FieldNote.objects.unscoped()
    serializer_class = FieldNoteSerializer
    lookup_field = "id"
    permission_classes = [IsAuthenticated]

    def safely_get_queryset(self, queryset: QuerySet) -> QuerySet:
        queryset = queryset.filter(team_id=self.team_id)
        field_note_status = self.request.query_params.get("field_note_status")
        if field_note_status:
            if field_note_status not in FieldNote.Status.values:
                raise ValidationError({"field_note_status": f"Must be one of: {', '.join(FieldNote.Status.values)}"})
            queryset = queryset.filter(field_note_status=field_note_status)
        host = self.request.query_params.get("host")
        if host:
            queryset = queryset.filter(host=host)
        return queryset.select_related("created_by").order_by("-created_at")