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.1 KB
Raw Blame
from datetime import datetime

from django.core.validators import URLValidator
from django.db import models
from django.utils import timezone

from rest_framework import serializers

from products.web_analytics.backend.weekly_digest import DigestDataStatus


class LlmsTxtFetchRequestSerializer(serializers.Serializer):
    url = serializers.URLField(
        max_length=2048,
        validators=[URLValidator(schemes=["http", "https"])],
        help_text="Public HTTP or HTTPS URL of the llms.txt file to load.",
    )


class LlmsTxtFetchResponseSerializer(serializers.Serializer):
    content = serializers.CharField(help_text="UTF-8 contents of the fetched llms.txt file.")
    url = serializers.URLField(help_text="Final public URL after redirects.")


class WoWChangeDirection(models.TextChoices):
    UP = "Up", "Up"
    DOWN = "Down", "Down"


class WoWChangeSerializer(serializers.Serializer):
    percent = serializers.IntegerField(help_text="Absolute percentage change, rounded to nearest integer.")
    direction = serializers.ChoiceField(
        choices=WoWChangeDirection.choices, help_text="Direction of the change relative to the prior period."
    )
    color = serializers.CharField(help_text="Hex color indicating whether the change is a positive or negative signal.")
    text = serializers.CharField(help_text="Short label, e.g. 'Up 12%'.")
    long_text = serializers.CharField(help_text="Verbose label, e.g. 'Up 12% from prior period'.")


class NumericMetricSerializer(serializers.Serializer):
    current = serializers.FloatField(help_text="Value for the most recent period.")
    previous = serializers.FloatField(allow_null=True, help_text="Value for the prior period, if available.")
    change = WoWChangeSerializer(allow_null=True, help_text="Period-over-period change, null when not meaningful.")


class DurationMetricSerializer(serializers.Serializer):
    current = serializers.CharField(help_text="Human-readable duration, e.g. '2m 34s'.")
    previous = serializers.CharField(allow_null=True, help_text="Prior-period duration, e.g. '2m 10s'.")
    change = WoWChangeSerializer(allow_null=True, help_text="Period-over-period change, null when not meaningful.")


class TopPageSerializer(serializers.Serializer):
    host = serializers.CharField(allow_blank=True, help_text="Host for the page, if recorded.")
    path = serializers.CharField(allow_blank=True, help_text="URL path.")
    visitors = serializers.IntegerField(help_text="Unique visitors in the period.")
    change = WoWChangeSerializer(
        allow_null=True, help_text="Period-over-period change in visitors, null when not meaningful."
    )


class TopSourceSerializer(serializers.Serializer):
    name = serializers.CharField(help_text="Initial referring domain.")
    visitors = serializers.IntegerField(help_text="Unique visitors from this source.")
    change = WoWChangeSerializer(
        allow_null=True, help_text="Period-over-period change in visitors, null when not meaningful."
    )


class GoalSerializer(serializers.Serializer):
    name = serializers.CharField(help_text="Goal name (action name).")
    conversions = serializers.IntegerField(help_text="Total conversions in the period.")
    change = WoWChangeSerializer(
        allow_null=True, help_text="Period-over-period change in conversions, null when not meaningful."
    )


class ProjectTimezoneDateTimeField(serializers.DateTimeField):
    def enforce_timezone(self, value: datetime) -> datetime:
        # DRF converts aware values to the active timezone, which is UTC, so the project offset is lost.
        if timezone.is_aware(value):
            return value
        return super().enforce_timezone(value)


class DigestMetadataSerializer(serializers.Serializer):
    data_status = serializers.ChoiceField(
        choices=DigestDataStatus.choices,
        help_text=(
            "How to read the headline numbers. 'ok': the headline has pageviews or sessions in the period. "
            "'no_web_sessions': the headline is zero, but the project has sessions in the period. None of them "
            "contain a $pageview or $screen event from a non-test account. Query the sessions table directly to "
            "count them. 'no_sessions': the project has no sessions in the period. 'unknown': the headline is zero, "
            "and the check for other sessions in the period failed. Query the sessions table directly to count them."
        ),
    )
    date_from = ProjectTimezoneDateTimeField(help_text="Start of the current period, in the project timezone.")
    date_to = ProjectTimezoneDateTimeField(help_text="End of the current period, in the project timezone.")
    timezone = serializers.CharField(help_text="Project timezone for the period boundaries.")
    filter_test_accounts = serializers.BooleanField(
        help_text=(
            "True when the headline metrics, top pages and top sources exclude events from test accounts. "
            "Goal conversions include them."
        )
    )
    notes = serializers.ListField(
        child=serializers.CharField(),
        help_text="Metric definitions to use when you compare the digest with a direct query.",
    )


class WeeklyDigestResponseSerializer(serializers.Serializer):
    visitors = NumericMetricSerializer(help_text="Unique visitors.")
    pageviews = NumericMetricSerializer(help_text="Total pageviews.")
    sessions = NumericMetricSerializer(help_text="Total sessions.")
    bounce_rate = NumericMetricSerializer(help_text="Bounce rate (0–100).")
    avg_session_duration = DurationMetricSerializer(help_text="Average session duration.")
    top_pages = TopPageSerializer(many=True, help_text="Top 5 pages by unique visitors.")
    top_sources = TopSourceSerializer(many=True, help_text="Top 5 traffic sources by unique visitors.")
    goals = GoalSerializer(many=True, help_text="Goal conversions.")
    metadata = DigestMetadataSerializer(
        help_text="Period, filters and metric definitions behind the numbers, and a status that explains a zero."
    )
    dashboard_url = serializers.URLField(help_text="Link to the Web analytics dashboard for this project.")


class RecapPersonaSerializer(serializers.Serializer):
    id = serializers.CharField(
        help_text=(
            "Stable persona identifier. One of: just_getting_started, conversion_machine, traffic_magnet, "
            "crowd_favorite, search_hog, word_of_mouth, loyal_following, rising_star, steady_hog."
        )
    )
    name = serializers.CharField(help_text="Display name for the persona, e.g. 'Traffic Magnet'.")
    emoji = serializers.CharField(help_text="Emoji representing the persona.")
    blurb = serializers.CharField(help_text="One-line explanation of why this persona was assigned this week.")
    color = serializers.CharField(help_text="Hex accent color for rendering the persona card.")


class RecapHighlightSerializer(serializers.Serializer):
    id = serializers.CharField(help_text="Stable highlight identifier, e.g. 'milestone', 'rising_page', 'top_source'.")
    emoji = serializers.CharField(help_text="Emoji for the highlight.")
    title = serializers.CharField(help_text="Short headline for the highlight, e.g. 'Rising star page'.")
    value = serializers.CharField(help_text="The standout value, e.g. a page path or visitor count.")
    detail = serializers.CharField(allow_blank=True, help_text="Supporting sentence for the highlight.")


class WebAnalyticsRecapResponseSerializer(WeeklyDigestResponseSerializer):
    persona = RecapPersonaSerializer(help_text="The single weekly persona assigned from this week's data.")
    highlights = RecapHighlightSerializer(
        many=True, help_text="Up to three screenshot-worthy superlatives for the week."
    )
    period_label = serializers.CharField(help_text="Human-readable period label, e.g. 'Last 7 days'.")
    period_start = serializers.DateField(help_text="First date included in the recap period, in the project timezone.")
    period_end = serializers.DateField(help_text="Final date included in the recap period, in the project timezone.")
    project_name = serializers.CharField(help_text="Name of the project this recap is for.")
    recap_url = serializers.URLField(help_text="Canonical link to this project's weekly recap.")