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.

23.9 KB
Raw Blame
from __future__ import annotations

from typing import Any, cast

from django.db import models

from drf_spectacular.utils import PolymorphicProxySerializer, extend_schema_field, extend_schema_serializer
from pydantic import BaseModel
from rest_framework import serializers

from posthog.schema import BreakdownFilter, CompareFilter, IntervalType

from products.dashboards.backend.constants import (
    DASHBOARD_GRID_COLUMN_COUNT,
    MAX_GROUP_KEY_LENGTH,
    MAX_GROUP_TITLE_LENGTH,
)
from products.dashboards.backend.models.dashboard import (
    DASHBOARD_GRID_COMPACTION_MODES,
    DASHBOARD_GRID_SPACING_GAPS,
    DASHBOARD_TILE_GROUP_DISPLAY_MODES,
    DashboardTileGroupColor,
)
from products.dashboards.backend.models.dashboard_tile import DashboardTileBadge
from products.dashboards.backend.widget_specs.pydantic_openapi import pydantic_config_field, pydantic_stub_serializer
from products.dashboards.backend.widget_specs.registry import EXPECTED_WIDGET_TYPES, WIDGET_SPECS

GROUPS_HELP_TEXT = (
    "Settings for tile groups, keyed by the tiles' group_key. Each group shows as a band of its tiles under a "
    "heading that viewers can open and close. Viewers who do not have bands yet see only the group title above "
    "its tiles. A write replaces the whole map. Send an empty object or null to remove all group settings."
)
GROUP_TITLES_HELP_TEXT = (
    "Deprecated: use groups. Titles for tile groups, keyed by group_key. A write replaces all titles and keeps "
    "the other group settings. Send an empty object or null to clear titles. Do not send it with groups."
)
GROUP_KEY_HELP_TEXT = (
    "Key that puts this tile in a group with the other tiles that have the same key on this dashboard. "
    "Set the group's title and style in the dashboard's groups. Null or an empty string removes the tile from its "
    "group."
)
BADGE_HELP_TEXT = (
    "Badge on the tile. winner shows a crown in the top left corner, for example to mark the best tile in a group. "
    "cheeky-hog shows a hedgehog when a person hovers over the tile. Null removes the badge. "
    "More than one tile in a group can have the winner badge."
)


DASHBOARD_TILE_GROUP_DEFAULTS = {"collapsed": False, "color": None}


# No field has a default, so a write stores only the settings the client sent.
class DashboardTileGroupSerializer(serializers.Serializer):
    title = serializers.CharField(
        max_length=MAX_GROUP_TITLE_LENGTH,
        required=False,
        allow_blank=True,
        help_text="Heading for the group. When it is blank or omitted, the heading shows the number of tiles.",
    )
    collapsed = serializers.BooleanField(
        required=False,
        help_text=(
            "Whether the group starts closed. Defaults to false. When a viewer opens or closes the group, their "
            "browser keeps that choice and it wins over this default. A closed group loads its tiles when a viewer "
            "opens it."
        ),
    )
    color = serializers.ChoiceField(
        choices=DashboardTileGroupColor.choices,
        required=False,
        allow_null=True,
        help_text="Color of a dot before the group heading. Null or omitted shows no dot.",
    )


WIDGET_BATCH_ADD_OPENAPI_HELP = (
    "Widget tiles to add atomically. Supported widget_type values: "
    + ", ".join(sorted(EXPECTED_WIDGET_TYPES))
    + ". Use dashboard-widget-catalog-list for per-type config_schema documentation."
)


class DashboardWidgetType(models.TextChoices):
    """Every registered widget type. test_widget_openapi_enums checks it against WIDGET_SPECS."""

    ACTIVITY_EVENTS_LIST = "activity_events_list"
    CANVAS_APP = "canvas_app"
    CONVERSATIONS_RECENT_TICKETS = "conversations_recent_tickets"
    ERROR_TRACKING_LIST = "error_tracking_list"
    EXPERIMENT_RESULTS = "experiment_results"
    EXPERIMENTS_LIST = "experiments_list"
    LOGS_LIST = "logs_list"
    METRICS_TABLE = "metrics_table"
    NOTEBOOK_WIDGET = "notebook_widget"
    SESSION_REPLAY_LIST = "session_replay_list"
    SURVEY_RESULTS = "survey_results"


# Batch tool schemas leave config untyped so they do not grow with each widget type.
# validate_widget_config still checks every config against its widget type.
WIDGET_CONFIG_BATCH_HELP = (
    "Widget configuration as a JSON object. Its keys depend on widget_type: read that type's config_schema "
    "from dashboard-widget-catalog-list. The API validates the config and returns a 400 that names each "
    "invalid field."
)


def _config_model_openapi_prefix(config_model: type[BaseModel]) -> str:
    name = config_model.__name__
    if name.endswith("WidgetConfig"):
        return name[: -len("Config")]
    if name.endswith("Config"):
        return name[: -len("Config")]
    return name


class _TileLayoutBoxOpenApiSerializer(serializers.Serializer):
    x = serializers.IntegerField(
        required=False,
        help_text="Column position in the dashboard grid (0-indexed).",
    )
    y = serializers.IntegerField(
        required=False,
        help_text="Row position in the dashboard grid (0-indexed).",
    )
    w = serializers.IntegerField(
        required=False,
        help_text="Width in grid columns. The desktop grid is 12 columns wide.",
    )
    h = serializers.IntegerField(required=False, help_text="Height in grid rows.")


class _TileLayoutsOpenApiSerializer(serializers.Serializer):
    sm = _TileLayoutBoxOpenApiSerializer(
        required=False,
        help_text="Layout for the standard (desktop) breakpoint. The grid is 12 columns wide.",
    )
    xs = _TileLayoutBoxOpenApiSerializer(
        required=False,
        help_text=(
            "Layout for the small (mobile) breakpoint, on a 1-column grid. The dashboard derives this layout "
            "from the sm order and heights, so a stored xs box does not change what renders."
        ),
    )


class _DashboardPatchTileLayoutBoxOpenApiSerializer(serializers.Serializer):
    x = serializers.IntegerField(
        min_value=0,
        max_value=DASHBOARD_GRID_COLUMN_COUNT - 1,
        help_text="Column position in the dashboard grid (0-indexed).",
    )
    y = serializers.IntegerField(min_value=0, help_text="Row position in the dashboard grid (0-indexed).")
    w = serializers.IntegerField(
        min_value=1,
        max_value=DASHBOARD_GRID_COLUMN_COUNT,
        help_text="Width in grid columns. The desktop grid is 12 columns wide.",
    )
    h = serializers.IntegerField(min_value=1, help_text="Height in grid rows.")


class _DashboardPatchTileLayoutsOpenApiSerializer(serializers.Serializer):
    sm = _DashboardPatchTileLayoutBoxOpenApiSerializer(
        help_text=(
            "Layout for the standard (desktop) breakpoint. The grid is 12 columns wide. A write replaces the "
            "tile's whole layout and the dashboard reads desktop placement from this box, so send it whenever "
            "you send layouts."
        ),
    )
    xs = _DashboardPatchTileLayoutBoxOpenApiSerializer(
        required=False,
        help_text=(
            "Layout for the small (mobile) breakpoint, on a 1-column grid. The dashboard derives this layout "
            "from the sm order and heights, so a stored xs box does not change what renders."
        ),
    )


class _AddDashboardWidgetTileFieldsOpenApiSerializer(serializers.Serializer):
    name = serializers.CharField(
        max_length=400,
        required=False,
        allow_null=True,
        allow_blank=True,
        help_text="Optional custom display name for the widget tile.",
    )
    description = serializers.CharField(
        required=False,
        allow_blank=True,
        help_text="Optional markdown description shown when show_description is enabled.",
    )
    layouts = _TileLayoutsOpenApiSerializer(
        required=False,
        help_text="Optional react-grid-layout positions keyed by breakpoint (sm, xs).",
    )
    show_description = serializers.BooleanField(
        required=False,
        help_text="Whether to show the description on the dashboard tile.",
    )


def _build_catalog_entry_serializers() -> dict[str, type[serializers.Serializer]]:
    catalog_entry_serializers: dict[str, type[serializers.Serializer]] = {}

    for widget_type, spec in WIDGET_SPECS.items():
        prefix = _config_model_openapi_prefix(spec.config_model)
        catalog_entry_serializers[widget_type] = type(
            f"{prefix}CatalogEntryOpenApiSerializer",
            (serializers.Serializer,),
            {
                "widget_type": serializers.ChoiceField(choices=[widget_type]),
                "group_id": serializers.CharField(),
                "group_label": serializers.CharField(),
                "label": serializers.CharField(),
                "description": serializers.CharField(),
                "config_schema": pydantic_config_field(
                    spec.config_model,
                    read_only=True,
                    help_text=(
                        "Config shape for this widget type. Build the config for the batch add and batch update "
                        "tools from it, because their schemas do not list config keys."
                    ),
                ),
                "required_product_access": serializers.CharField(required=False, allow_null=True),
                "live": serializers.BooleanField(
                    help_text=(
                        "Whether tiles of this type self-update in real time after load. Live tiles show a "
                        "fixed real-time window and cannot apply test-account filtering to the stream, so "
                        "their config takes neither dateRange nor filterTestAccounts."
                    ),
                ),
            },
        )

    return catalog_entry_serializers


WIDGET_CONFIG_SERIALIZERS: dict[str, type[serializers.Serializer]] = {
    widget_type: pydantic_stub_serializer(spec.config_model) for widget_type, spec in WIDGET_SPECS.items()
}
_WIDGET_CATALOG_ENTRY_SERIALIZERS = _build_catalog_entry_serializers()

DashboardWidgetConfigOpenApi = PolymorphicProxySerializer(
    component_name="DashboardWidgetConfig",
    serializers=list(WIDGET_CONFIG_SERIALIZERS.values()),
    resource_type_field_name=None,
)


@extend_schema_field(DashboardWidgetConfigOpenApi)
class DashboardWidgetConfigField(serializers.JSONField):
    """JSONField annotated with per-widget-type config schemas for OpenAPI generation."""

    pass


@extend_schema_serializer(component_name="AddDashboardWidgetRequest")
class _AddDashboardWidgetRequestOpenApiSerializer(_AddDashboardWidgetTileFieldsOpenApiSerializer):
    widget_type = serializers.ChoiceField(
        choices=DashboardWidgetType.choices,
        help_text="Widget type to add. Use dashboard-widget-catalog-list to pick one.",
    )
    config = serializers.DictField(child=serializers.JSONField(), help_text=WIDGET_CONFIG_BATCH_HELP)


AddDashboardWidgetRequestOpenApi = _AddDashboardWidgetRequestOpenApiSerializer()


class _UpdateDashboardWidgetTileFieldsOpenApiSerializer(serializers.Serializer):
    tile_id = serializers.IntegerField(
        help_text="ID of the widget tile to update. Use dashboard-get to look up widget tile IDs.",
    )
    name = serializers.CharField(
        max_length=400,
        required=False,
        allow_null=True,
        allow_blank=True,
        help_text="New display name for the widget. Empty string or null clears it; omit to leave unchanged.",
    )
    description = serializers.CharField(
        required=False,
        allow_blank=True,
        help_text="New markdown description for the widget. Omit to leave unchanged.",
    )


@extend_schema_serializer(component_name="UpdateDashboardWidgetRequest")
class _UpdateDashboardWidgetRequestOpenApiSerializer(_UpdateDashboardWidgetTileFieldsOpenApiSerializer):
    widget_type = serializers.ChoiceField(
        choices=DashboardWidgetType.choices,
        required=False,
        help_text="The tile's widget type. It cannot be changed, so omit it or pass the current type.",
    )
    config = serializers.DictField(
        child=serializers.JSONField(),
        required=False,
        help_text=(
            f"{WIDGET_CONFIG_BATCH_HELP} Each top-level key you send replaces the stored value, and keys you "
            "leave out stay as they are. Omit config to leave it unchanged."
        ),
    )


UpdateDashboardWidgetRequestOpenApi = _UpdateDashboardWidgetRequestOpenApiSerializer()

WidgetCatalogEntryOpenApi = PolymorphicProxySerializer(
    component_name="WidgetCatalogEntry",
    serializers=cast("dict[str, Any]", _WIDGET_CATALOG_ENTRY_SERIALIZERS),
    resource_type_field_name="widget_type",
)


class WidgetCatalogResponseSerializer(serializers.Serializer):
    results = serializers.ListField(
        child=WidgetCatalogEntryOpenApi,
        help_text="Registered dashboard widget types.",
    )


class DashboardPatchWidgetOpenApiSerializer(serializers.Serializer):
    id = serializers.UUIDField(
        required=False,
        help_text="Existing widget row ID when updating a widget tile via dashboard PATCH.",
    )
    widget_type = serializers.ChoiceField(
        choices=DashboardWidgetType.choices,
        required=False,
        help_text="Widget type identifier (cannot be changed on update).",
    )
    config = DashboardWidgetConfigField(
        required=False,
        help_text="Widget-specific configuration. Shape depends on the tile's widget_type.",
    )
    name = serializers.CharField(
        max_length=400,
        required=False,
        allow_null=True,
        allow_blank=True,
        help_text="Optional custom display name for the widget tile.",
    )
    description = serializers.CharField(
        required=False,
        allow_blank=True,
        help_text="Optional markdown description shown when show_description is enabled.",
    )


class DashboardPatchTileOpenApiSerializer(serializers.Serializer):
    id = serializers.IntegerField(required=False, help_text="Dashboard tile ID to update.")
    layouts = _DashboardPatchTileLayoutsOpenApiSerializer(
        required=False,
        help_text=(
            "Grid position and size per breakpoint. Works for every tile type, including insight tiles. "
            "A write replaces the tile's whole layout, so send a complete sm box rather than the one value "
            "you want to change. Boxes are stored as sent and overlaps are not resolved, so send sm boxes "
            "that do not overlap, and include every tile you move in the same request."
        ),
    )
    show_description = serializers.BooleanField(
        required=False,
        help_text=(
            "Whether to show the tile's description underneath its title on the dashboard. Works for every "
            "tile type. The description itself is unaffected and still comes from the tile's insight, text, "
            "or widget content — this only toggles whether it renders on the dashboard."
        ),
    )
    group_key = serializers.CharField(
        max_length=MAX_GROUP_KEY_LENGTH,
        required=False,
        allow_null=True,
        allow_blank=True,
        help_text=GROUP_KEY_HELP_TEXT,
    )
    badge = serializers.ChoiceField(
        choices=DashboardTileBadge.choices,
        required=False,
        allow_null=True,
        help_text=BADGE_HELP_TEXT,
    )
    widget = DashboardPatchWidgetOpenApiSerializer(required=False, help_text="Nested widget row updates.")


@extend_schema_field(BreakdownFilter)  # type: ignore[arg-type]
class DashboardBreakdownFilterField(serializers.JSONField):
    pass


@extend_schema_field(CompareFilter)  # type: ignore[arg-type]
class DashboardCompareFilterField(serializers.JSONField):
    pass


class DashboardFiltersOpenApiSerializer(serializers.Serializer):
    """OpenAPI-only shape for a dashboard's filters object (agents/MCP).

    Documents the dashboard-level filters that act as the single source of truth for the
    dashboard's tiles. Runtime persistence reads the raw ``filters`` dict from the request body, so
    extra keys are accepted, but these are the ones agents should set.
    """

    date_from = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Dashboard-level start of the date range, e.g. '-30d', '-7d', or an ISO date. Applies to all tiles.",
    )
    date_to = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Dashboard-level end of the date range, e.g. '-1d' or an ISO date. Null/omitted means up to now.",
    )
    properties = serializers.JSONField(
        required=False,
        help_text="Dashboard-level property filters applied to every tile (PostHog property filter group).",
    )
    breakdown_filter = DashboardBreakdownFilterField(
        required=False,
        allow_null=True,
        help_text=(
            "Dashboard-level breakdown applied to every tile that supports one, replacing the tile's own breakdown. "
            'Example: {"breakdown_type": "event", "breakdown": "$browser"}. Null clears it.'
        ),
    )
    # nosemgrep: choices-need-a-class -- generated query schema enum, ENUM_NAME_OVERRIDES pins IntervalTypeEnum
    interval = serializers.ChoiceField(
        choices=[interval.value for interval in IntervalType],
        required=False,
        allow_null=True,
        help_text="Time granularity forced onto every tile that supports one. Null means each tile keeps its own.",
    )
    compareFilter = DashboardCompareFilterField(
        required=False,
        allow_null=True,
        help_text="Period comparison forced onto every tile that supports one. Null means each tile keeps its own.",
    )
    filterTestAccounts = serializers.BooleanField(
        required=False,
        allow_null=True,
        help_text="True forces test accounts out of every tile, false forces them in, null keeps each tile's setting.",
    )


class BreakdownColorConfigSerializer(serializers.Serializer):
    breakdownValue = serializers.CharField(
        allow_blank=True,
        help_text="The breakdown value this color applies to, as it appears in the chart legend.",
    )
    # A token names a slot in the dashboard's color theme, not a color. getColorFromToken parses the
    # N out and indexes the theme with it, so any other string yields theme['preset-NaN'], which is
    # undefined. The pattern rather than a fixed range, because a theme may carry more slots than the
    # default palette and the token wraps past its end.
    #
    # The slot starts at 1 and its digits must be ASCII. getColorFromToken wraps the index as
    # ((N - 1) % slots) + 1, so `preset-0` reads theme['preset-0'], and JavaScript parseInt reads
    # another script's digits as NaN.
    colorToken = serializers.RegexField(
        r"^preset-[1-9][0-9]*$",
        allow_null=True,
        help_text=(
            "Palette slot to color the value with, as `preset-1` upwards. Not a CSS color: a hex "
            "value is rejected. Null leaves the value on its default color."
        ),
    )
    breakdownType = serializers.CharField(
        required=False,
        allow_null=True,
        help_text="Breakdown type the value came from, such as `event`, `person`, `session`, or `cohort`.",
    )
    # Null means the same as omitted for both keys below: the frontend reads
    # `breakdownProperty != null` for property scoping, and treats an entry with no source as a
    # manual pin. So an explicit null must not fail a write.
    breakdownProperty = serializers.CharField(
        required=False,
        allow_null=True,
        help_text=(
            "Breakdown property the color is scoped to, so the color applies only to tiles that break "
            "down by that property. Omit to apply it under every property."
        ),
    )
    # `source` is also the name of a Field attribute on the Serializer base class, which mypy reads as
    # a shadowed assignment. SerializerMetaclass pops every declared field out of the class namespace,
    # so the base attribute survives and the entry key stays `source`, which is what the frontend
    # persists.
    source = serializers.ChoiceField(  # type: ignore[assignment]
        choices=["auto", "manual"],
        required=False,
        allow_null=True,
        help_text="`manual` for a color a person picked, `auto` for one the dashboard assigned.",
    )


class PatchedDashboardOpenApiSerializer(serializers.Serializer):
    """OpenAPI-only PATCH body for dashboards (agents/MCP).

    Must be a superset of ``dashboard_patch_runtime_openapi_field_names()`` — ``extend_schema(request=...)``
    replaces the inferred schema entirely. Contract: ``test_dashboard_openapi.py``.
    """

    name = serializers.CharField(max_length=400, required=False, allow_null=True)
    description = serializers.CharField(required=False, allow_blank=True)
    pinned = serializers.BooleanField(required=False)
    filters = DashboardFiltersOpenApiSerializer(
        required=False,
        help_text="Dashboard-level filters (date range, properties, breakdown, interval, comparison) applied across all tiles as the source of truth.",
    )
    breakdown_colors = serializers.ListField(
        child=BreakdownColorConfigSerializer(),
        required=False,
        allow_null=True,
        help_text=(
            "Colors pinned to specific breakdown values across the dashboard's tiles. "
            "A list of entries, not an object keyed by breakdown value. Send an empty list to clear them."
        ),
    )
    data_color_theme_id = serializers.IntegerField(
        required=False,
        allow_null=True,
        help_text="ID of the color theme used for chart visualizations.",
    )
    tags = serializers.ListField(child=serializers.CharField(), required=False)
    quick_filter_ids = serializers.ListField(
        child=serializers.CharField(),
        required=False,
        allow_null=True,
        help_text="List of quick filter IDs associated with this dashboard.",
    )
    grid_spacing = serializers.ChoiceField(
        choices=tuple(DASHBOARD_GRID_SPACING_GAPS),
        required=False,
        help_text="Named tile density preset. Use tight, condensed, standard, relaxed, or wide.",
    )
    layout_compaction = serializers.ChoiceField(
        choices=DASHBOARD_GRID_COMPACTION_MODES,
        required=False,
        help_text=(
            "How tiles rearrange after a move or resize. vertical stacks tiles upward, horizontal stacks tiles "
            "to the left, and stable preserves positions while moving colliding tiles."
        ),
    )
    group_display = serializers.ChoiceField(
        choices=DASHBOARD_TILE_GROUP_DISPLAY_MODES,
        required=False,
        help_text=(
            "How tile groups show. sections shows each group as a band that opens and closes. tabs shows one "
            "group at a time, and tiles outside any group get their own first tab."
        ),
    )
    groups = serializers.DictField(
        child=DashboardTileGroupSerializer(),
        required=False,
        allow_null=True,
        help_text=GROUPS_HELP_TEXT,
    )
    group_titles = serializers.DictField(
        child=serializers.CharField(max_length=MAX_GROUP_TITLE_LENGTH),
        required=False,
        allow_null=True,
        help_text=GROUP_TITLES_HELP_TEXT,
    )
    tiles = DashboardPatchTileOpenApiSerializer(
        many=True,
        required=False,
        help_text=(
            "Dashboard tiles to update, each identified by its tile id. Any tile type accepts `layouts` to set "
            "its grid position and size. Widget tiles also accept nested widget.config patches."
        ),
    )
    use_template = serializers.CharField(
        required=False,
        allow_blank=True,
        help_text="Template key to create the dashboard from a predefined template.",
    )
    use_dashboard = serializers.IntegerField(
        required=False,
        allow_null=True,
        help_text="ID of an existing dashboard to duplicate.",
    )
    delete_insights = serializers.BooleanField(
        required=False,
        default=False,
        help_text="When deleting, also delete insights that are only on this dashboard.",
    )


def __getattr__(name: str) -> Any:
    for serializer in WIDGET_CONFIG_SERIALIZERS.values():
        if serializer.__name__ == name:
            return serializer
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")