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.

55.2 KB
Raw Blame
"""The subscription API's writes: the rules a create or an update must pass, the write, and the delivery it starts."""

import uuid
import asyncio
import dataclasses
from collections.abc import Callable
from typing import ClassVar, Optional

from django.conf import settings
from django.db import transaction
from django.db.models import Q

import posthoganalytics
from temporalio.exceptions import WorkflowAlreadyStartedError

from posthog.schema import SubscriptionAIContextLimit

from posthog.cloud_utils import is_cloud
from posthog.constants import SUBSCRIPTION_AI_PROMPT_FEATURE_FLAG_KEY
from posthog.event_usage import AnalyticsProps, groups
from posthog.exceptions_capture import capture_exception
from posthog.integrations import IntegrationManager, IntegrationNotFound
from posthog.models.activity_logging.activity_log import Change, Detail, log_activity
from posthog.models.activity_logging.model_activity import get_was_impersonated
from posthog.models.integration import SlackIntegration
from posthog.models.organization import Organization
from posthog.models.team import Team
from posthog.models.user import User
from posthog.query_creator_access import (
    CreatorLeftOrganizationError,
    assert_creator_can_run,
    describe_owner_unavailable,
    owner_unavailable_code,
)
from posthog.resource_limits import LimitKey, check_count_limit
from posthog.security.url_validation import is_microsoft_teams_webhook_url
from posthog.slo.context import SloSpec, slo_operation
from posthog.slo.types import SloArea, SloOperation
from posthog.temporal.common.client import sync_connect
from posthog.utils import human_list

from products.access_control.backend.facade.user_access_control import UserAccessControl, UserAccessControlError
from products.dashboards.backend.models.dashboard import Dashboard
from products.product_analytics.backend.facade.api import insights_including_soft_deleted_for_team
from products.product_analytics.backend.facade.models import Insight
from products.subscriptions.backend.facade.contracts import (
    UNSET,
    ManualDeliveryOutcome,
    ManualDeliveryResult,
    ProcessSubscriptionWorkflowInputs,
    PromptRejectedError,
    SubscriptionContextTarget,
    SubscriptionPermissionDeniedError,
    SubscriptionQuotaExceededError,
    SubscriptionRecord,
    SubscriptionRequestInvalidError,
    SubscriptionTriggerType,
    SubscriptionWrite,
)
from products.subscriptions.backend.logic.auto_disable import validate_re_enable
from products.subscriptions.backend.logic.subscription_query_access import (
    denied_resources_in_subscription,
    should_check_table_access,
)
from products.subscriptions.backend.logic.subscription_utils import MAX_INSIGHTS
from products.subscriptions.backend.logic.teams_subscriptions import (
    TEAMS_WEBHOOK_URL_ERROR,
    TEAMS_WEBHOOK_URL_MASKED_ERROR,
)
from products.subscriptions.backend.models.subscription import Subscription, attribute_subscription_saves
from products.subscriptions.backend.models.subscription_context import SubscriptionContext, context_ref
from products.subscriptions.backend.temporal.ai_subscription.spec_generator import (
    PROMPT_MAX_LENGTH as AI_PROMPT_MAX_LENGTH,
    sanitize_prompt,
)

from ee.billing.quota_limiting import QuotaLimitingCaches, QuotaResource, is_team_limited

from .subscription_reads import context_rows, subscription_record
from .summary_quota import invalidate_summary_quota_cache, validate_summary_enabled_org_limit
from .visibility import blocked_target_ids, require_viewer_access, viewable_queryset

MAX_AI_SUBSCRIPTION_CONTEXTS: int = int(SubscriptionAIContextLimit.model_fields["root"].default)
AI_DELIVERY_DISPLAY_FIELDS = frozenset(
    {"include_images", "include_feedback", "include_manage_link", "include_posthog_hint"}
)

# The write fields whose model attribute has a different name. Every other field keeps its name.
_MODEL_ATTRIBUTE_NAMES: dict[str, str] = {
    "dashboard_id": "dashboard",
    "insight_id": "insight",
    "dashboard_export_insight_ids": "dashboard_export_insights",
}


def _capture_post_write_failure(exc: Exception) -> None:
    """Report a failure that happens after the write is committed.

    `capture_exception` reads query tags and logs, neither of which is guarded, so a fault in
    reporting would propagate and fail a request whose write already landed.
    """
    try:
        capture_exception(exc)
    except Exception:
        pass


def _ai_create_gate_reason(organization: Organization, distinct_id: str) -> Optional[str]:
    if not settings.DEBUG and not is_cloud():
        return "AI subscriptions are only available in PostHog Cloud."
    if not organization.is_ai_data_processing_approved:
        return "Your organization must approve AI data processing before creating AI subscriptions."
    # Per-user gate so people can self-enable via feature previews (early access) — the flag is
    # person-based. AI credits and the subscription limit stay org-scoped, enforced separately.
    # Non-user callers get a synthetic team_<id> distinct_id that never matches → fails closed.
    if not posthoganalytics.feature_enabled(
        SUBSCRIPTION_AI_PROMPT_FEATURE_FLAG_KEY,
        distinct_id,
        only_evaluate_locally=False,
        send_feature_flag_events=False,
    ):
        return "AI subscriptions are not enabled for your account."
    return None


def _write_attrs(write: SubscriptionWrite) -> dict:
    """The write's fields that are set, keyed the way the model names them.

    The request field checked that a named dashboard or insight exists. Each one resolves to its row
    where validate() checks its team.
    """
    attrs: dict = {}
    for field in dataclasses.fields(write):
        value = getattr(write, field.name)
        if value is UNSET:
            continue
        attrs[_MODEL_ATTRIBUTE_NAMES.get(field.name, field.name)] = value
    return attrs


def owner_unavailable_message(owner: User | None, error: Exception) -> str:
    """The refusal for a re-enable the owner cannot run, naming the owner and the cause."""
    return f"Can't re-enable this subscription. {describe_owner_unavailable(owner, error)}"


class _SubscriptionWrite:
    """One create or update, checked against the rules that span fields, the team and the plan."""

    FIELDS_THAT_TRIGGER_REDELIVERY: ClassVar[tuple[str, ...]] = (
        "target_value",
        "target_type",
        "integration_id",
        "delivery_config",
        "prompt",
        "insight_id",
        "dashboard_id",
    )

    def __init__(
        self,
        *,
        team: Team,
        organization: Organization,
        user: User,
        viewer: UserAccessControl,
        instance: Subscription | None,
        partial: bool,
        is_create_request: bool,
        analytics_props: AnalyticsProps,
    ) -> None:
        self.team = team
        self.team_id = team.id
        self.organization = organization
        self.user = user
        self.viewer = viewer
        self.instance = instance
        self.partial = partial
        self.is_create_request = is_create_request
        self.analytics_props = analytics_props

    def _caller_distinct_id(self) -> str:
        if self.user and getattr(self.user, "distinct_id", None):
            return str(self.user.distinct_id)
        return f"team_{self.team_id}"

    def _validate_insight_content(self, attrs: dict, existing: Optional[Subscription]) -> None:
        if not (attrs.get("insight") or (existing and existing.insight_id)):
            raise SubscriptionRequestInvalidError({"insight": ["Insight is required for insight subscriptions."]})
        if attrs.get("dashboard") or attrs.get("prompt"):
            raise SubscriptionRequestInvalidError(
                {"insight": ["Insight subscriptions cannot also set dashboard or prompt."]}
            )

    def _validate_dashboard_content(self, attrs: dict, existing: Optional[Subscription]) -> None:
        if not (attrs.get("dashboard") or (existing and existing.dashboard_id)):
            raise SubscriptionRequestInvalidError({"dashboard": ["Dashboard is required for dashboard subscriptions."]})
        if attrs.get("insight") or attrs.get("prompt"):
            raise SubscriptionRequestInvalidError(
                {"dashboard": ["Dashboard subscriptions cannot also set insight or prompt."]}
            )

    def _validate_ai_content(self, attrs: dict, existing: Optional[Subscription]) -> None:
        if attrs.get("insight") or attrs.get("dashboard"):
            raise SubscriptionRequestInvalidError(
                {"prompt": ["AI subscriptions cannot also set insight or dashboard."]}
            )
        # Explicit-key check so a PATCH sending prompt="" doesn't fall through to the stale value.
        prompt = (attrs["prompt"] if "prompt" in attrs else (existing.prompt if existing else None)) or ""
        prompt = prompt.strip()
        if not prompt:
            raise SubscriptionRequestInvalidError({"prompt": ["Prompt is required for AI subscriptions."]})
        if len(prompt) > AI_PROMPT_MAX_LENGTH:
            raise SubscriptionRequestInvalidError(
                {"prompt": [f"Prompt cannot exceed {AI_PROMPT_MAX_LENGTH} characters."]}
            )
        if "prompt" in attrs:
            attrs["prompt"] = prompt
        target_type = attrs.get("target_type") or (existing.target_type if existing else None)
        if target_type and target_type not in (
            Subscription.SubscriptionTarget.EMAIL,
            Subscription.SubscriptionTarget.SLACK,
            Subscription.SubscriptionTarget.TEAMS,
        ):
            raise SubscriptionRequestInvalidError(
                {"target_type": ["AI subscriptions only support email, slack, or teams delivery."]}
            )
        # Gates fire on create only; existing AI subs stay editable.
        if existing is None:
            gate_reason = _ai_create_gate_reason(self.organization, self._caller_distinct_id())
            if gate_reason is not None:
                raise SubscriptionRequestInvalidError(gate_reason)

    def _validate_contexts(
        self, contexts: tuple[SubscriptionContextTarget, ...]
    ) -> list[dict[str, Insight | Dashboard]]:
        if len(contexts) > MAX_AI_SUBSCRIPTION_CONTEXTS:
            raise SubscriptionRequestInvalidError(
                {"contexts": [f"Select no more than {MAX_AI_SUBSCRIPTION_CONTEXTS} dashboards and insights."]}
            )

        identifiers = [(context.kind, context.id) for context in contexts]
        if len(set(identifiers)) != len(identifiers):
            raise SubscriptionRequestInvalidError({"contexts": ["Select each dashboard or insight only once."]})

        dashboard_ids = {identifier for kind, identifier in identifiers if kind == "dashboard"}
        insight_ids = {identifier for kind, identifier in identifiers if kind == "insight"}
        team_id = self.team.id
        dashboards = {
            dashboard.id: dashboard
            for dashboard in Dashboard.objects_including_soft_deleted.filter(team_id=team_id, id__in=dashboard_ids)
        }
        insights = {
            insight.id: insight
            for insight in insights_including_soft_deleted_for_team(team_id=team_id, insight_ids=insight_ids)
        }
        validated_contexts: list[dict[str, Insight | Dashboard]] = []

        for kind, identifier in identifiers:
            target = dashboards.get(identifier) if kind == "dashboard" else insights.get(identifier)
            if target is None:
                raise SubscriptionRequestInvalidError(
                    {"contexts": [f"This {kind} is not in your team, or no longer exists."]}
                )
            if target.deleted:
                raise SubscriptionRequestInvalidError({"contexts": [f"This {kind} has been deleted."]})
            if not self.viewer.check_access_level_for_object(target, "viewer"):
                raise SubscriptionRequestInvalidError(
                    {"contexts": [f"Viewer access to this {kind} is required. Ask an admin to grant you access."]}
                )
            if isinstance(target, Dashboard):
                self._require_viewer_access_to_every_live_tile(target, error_field="contexts")
            validated_contexts.append({kind: target})

        return validated_contexts

    def validate(self, attrs: dict) -> dict:
        # Re-run the free-tier cap on create AND on restore (deleted: true → false) —
        # a soft-deleted row frees its slot, so PATCHing one back to active re-occupies
        # one and must respect the limit, otherwise a free-tier team could soft-delete +
        # create + restore its way past the cap.
        is_create = self.is_create_request
        is_restoring = self.instance is not None and self.instance.deleted and attrs.get("deleted") is False
        if is_create or is_restoring:
            msg = Subscription.check_subscription_limit(self.team_id, self.organization)
            if msg:
                raise SubscriptionRequestInvalidError({"subscription": [msg]})

        existing = self.instance

        if attrs.get("dashboard"):
            # Looked up in any team, so a dashboard of another team gets this error rather than a missing-row error.
            # nosemgrep: idor-lookup-without-team
            attrs["dashboard"] = Dashboard.objects.get(pk=attrs["dashboard"])
            if attrs["dashboard"].team.id != self.team_id:
                raise SubscriptionRequestInvalidError({"dashboard": ["This dashboard does not belong to your team."]})

        if attrs.get("insight"):
            # An insight of another project is not returned, and one of a sibling environment fails the team check.
            team_insights = insights_including_soft_deleted_for_team(
                team_id=self.team_id, insight_ids=[attrs["insight"]]
            )
            if not team_insights or team_insights[0].team.id != self.team_id:
                raise SubscriptionRequestInvalidError({"insight": ["This insight does not belong to your team."]})
            attrs["insight"] = team_insights[0]

        turning_off = attrs.get("deleted") is True or attrs.get("enabled") is False
        for field in ("dashboard", "insight"):
            target = attrs.get(field) or getattr(existing, field, None)
            if target is not None and not (target.deleted and turning_off):
                require_viewer_access(self.viewer, target, field)

        if existing is None:
            # Create: a subscription must export an insight, a dashboard, or an AI prompt.
            if not attrs.get("dashboard") and not attrs.get("insight") and not attrs.get("prompt"):
                raise SubscriptionRequestInvalidError("A subscription must have an insight, a dashboard, or a prompt.")

        try:
            if existing is not None:
                # `resource_type` derives from the row's content; a corrupt row (e.g. a prompt
                # nulled directly in the DB) leaves nothing to derive from and raises.
                resource_type = existing.resource_type
            else:
                insight, dashboard = attrs.get("insight"), attrs.get("dashboard")
                resource_type = Subscription.derive_resource_type(
                    insight.id if insight else None, dashboard.id if dashboard else None, attrs.get("prompt")
                )
        except ValueError as exc:
            raise SubscriptionRequestInvalidError(str(exc))
        # The prompt merge below folds the stored config into `attrs`, so keep what the caller
        # actually sent. A stored option that the request never names must not reject the
        # request, because that leaves the row impossible to edit.
        submitted_delivery_config = attrs.get("delivery_config") or {}
        if (
            resource_type == Subscription.ResourceType.AI_PROMPT
            and self.partial
            and existing is not None
            and "delivery_config" in attrs
        ):
            existing_delivery_config = existing.delivery_config if isinstance(existing.delivery_config, dict) else {}
            attrs["delivery_config"] = {**existing_delivery_config, **attrs["delivery_config"]}
        content_validators: dict[str, Callable[[dict, Optional[Subscription]], None]] = {
            Subscription.ResourceType.INSIGHT: self._validate_insight_content,
            Subscription.ResourceType.DASHBOARD: self._validate_dashboard_content,
            Subscription.ResourceType.AI_PROMPT: self._validate_ai_content,
        }
        validate_for_resource_type = content_validators.get(resource_type)
        # Fail soft on an unexpected resource_type (e.g. a stale DB row) — a 400 is
        # diagnosable, an unhandled KeyError surfaces as a 500.
        if validate_for_resource_type is None:
            raise SubscriptionRequestInvalidError({"resource_type": [f"Unsupported resource_type: {resource_type}."]})
        if resource_type != Subscription.ResourceType.AI_PROMPT and attrs.get("ai_prompt_config"):
            raise SubscriptionRequestInvalidError(
                {
                    "ai_prompt_config": [
                        "ai_prompt_config only applies to prompt subscriptions. This subscription has "
                        f"resource_type '{resource_type}', so remove it from the request."
                    ]
                }
            )
        if "contexts" in attrs:
            if resource_type != Subscription.ResourceType.AI_PROMPT:
                if attrs["contexts"]:
                    raise SubscriptionRequestInvalidError({"contexts": ["Context only applies to AI subscriptions."]})
                # Every read carries an empty list here, so a client saving what it read sends one back.
                attrs.pop("contexts")
            else:
                attrs["contexts"] = self._validate_contexts(attrs["contexts"])
        validate_for_resource_type(attrs, existing)

        self._validate_dashboard_export_subscription(attrs)

        target_type = attrs.get("target_type") or (self.instance.target_type if self.instance else None)
        if (
            self.instance
            and self.instance.target_type == Subscription.SubscriptionTarget.TEAMS
            and target_type != Subscription.SubscriptionTarget.TEAMS
            and "target_value" not in attrs
        ):
            raise SubscriptionRequestInvalidError(
                {"target_value": ["A new target value is required when changing from Microsoft Teams."]}
            )
        # Use explicit-key check for integration_id so a deliberate `null` in the PATCH
        # body falls through to the validation below — `or` would silently coalesce
        # to the stale instance value and pass `validate_re_enable` with the wrong id.
        integration_id = (
            attrs["integration_id"]
            if "integration_id" in attrs
            else (self.instance.integration_id if self.instance else None)
        )
        effective_delivery_config = (
            attrs["delivery_config"]
            if "delivery_config" in attrs
            else (self.instance.delivery_config if self.instance else None)
        ) or {}
        # A prompt report on a target that ignores the option still delivers, so only a value the request
        # sends is checked. Older prompt rows can store it on an email target and must stay editable.
        gallery_enabled = (
            submitted_delivery_config
            if resource_type == Subscription.ResourceType.AI_PROMPT
            else effective_delivery_config
        ).get("post_all_insights_in_main_message")
        if resource_type != Subscription.ResourceType.AI_PROMPT:
            unsupported = sorted(AI_DELIVERY_DISPLAY_FIELDS & submitted_delivery_config.keys())
            if unsupported:
                verb, pronoun = ("applies", "it") if len(unsupported) == 1 else ("apply", "them")
                raise SubscriptionRequestInvalidError(
                    {
                        "delivery_config": [
                            f"{human_list(unsupported)} only {verb} to prompt subscriptions. "
                            f"This subscription has resource_type '{resource_type}', "
                            f"so remove {pronoun} from delivery_config."
                        ]
                    }
                )

        # Reject re-enables of subscriptions whose delivery prerequisite is still
        # permanently broken — otherwise the next delivery would just auto-disable
        # them again.
        is_re_enabling = self.instance is not None and attrs.get("enabled") is True and self.instance.enabled is False
        if is_re_enabling:
            error_message = validate_re_enable(target_type, integration_id)
            if error_message:
                raise SubscriptionRequestInvalidError({"enabled": [error_message]})
            # Deliveries run as the owner, so an owner who cannot run them would only get it disabled again.
            assert existing is not None
            # The owner must be able to run the target this write leaves, not the one it replaces.
            dashboard = attrs.get("dashboard") or existing.dashboard
            insight = attrs.get("insight") or existing.insight
            try:
                assert_creator_can_run(existing.created_by, self.team, dashboard, insight)
            except (CreatorLeftOrganizationError, UserAccessControlError) as error:
                raise SubscriptionRequestInvalidError(
                    {"enabled": [owner_unavailable_message(existing.created_by, error)]},
                    code=owner_unavailable_code(error),
                ) from None
            # AI subs auto-disable on PromptRejectedError (deleted creator, prompt now
            # fails sanitization). The delivery path will just re-disable on the next
            # tick unless the underlying cause is fixed by this PATCH.
            if resource_type == Subscription.ResourceType.AI_PROMPT:
                prompt_after = attrs.get("prompt") if "prompt" in attrs else (existing.prompt if existing else None)
                created_by_after = existing.created_by if existing else None
                if created_by_after is None:
                    raise SubscriptionRequestInvalidError(
                        {"enabled": ["Cannot re-enable AI subscription: the original creator is unavailable."]}
                    )
                try:
                    sanitize_prompt(prompt_after)
                except PromptRejectedError as exc:
                    raise SubscriptionRequestInvalidError(
                        {"enabled": [f"Cannot re-enable AI subscription: prompt is invalid ({exc})."]}
                    )

        # Reject mutations that would land `next_delivery_date=None` — `enabled=True`
        # with a null next_delivery_date is invisible to the scheduler (the
        # `__lte=now` filter in `fetch_due_subscriptions_activity` drops nulls).
        # Three reachable paths: re-enable an exhausted sub, create one with a bad
        # rrule, or PATCH an active sub's schedule into exhaustion.
        check_schedule = (
            is_re_enabling
            or self.instance is None
            or (self.instance is not None and self.instance.enabled and bool(Subscription.RRULE_FIELDS & attrs.keys()))
        )
        if check_schedule and Subscription.project_next_delivery_date(instance=self.instance, **attrs) is None:
            base = "Subscription schedule has reached its end date. Extend until_date or remove count"
            if is_re_enabling:
                raise SubscriptionRequestInvalidError({"enabled": [f"{base} before re-enabling."]})
            if self.instance is None:
                raise SubscriptionRequestInvalidError({"start_date": [f"{base}."]})
            raise SubscriptionRequestInvalidError(f"{base}.")

        destination_changed = bool({"target_type", "target_value", "integration_id", "delivery_config"} & attrs.keys())
        validate_destination = existing is None or not turning_off or destination_changed
        if target_type == Subscription.SubscriptionTarget.TEAMS and validate_destination:
            submitted = (attrs.get("target_value") or "").strip()
            if self.instance and submitted and submitted == self.instance.recipient_label:
                raise SubscriptionRequestInvalidError({"target_value": [TEAMS_WEBHOOK_URL_MASKED_ERROR]})
            target_value = submitted or (self.instance.target_value if self.instance else "")
            if not is_microsoft_teams_webhook_url(target_value):
                raise SubscriptionRequestInvalidError({"target_value": [TEAMS_WEBHOOK_URL_ERROR]})

        if target_type == Subscription.SubscriptionTarget.SLACK and validate_destination:
            if not integration_id:
                raise SubscriptionRequestInvalidError(
                    {"integration_id": ["A Slack integration is required for Slack subscriptions."]}
                )
            try:
                integration = IntegrationManager.slack.oauth.get(self.team_id, integration_id)
            except IntegrationNotFound:
                raise SubscriptionRequestInvalidError(
                    {"integration_id": ["This integration does not exist or does not belong to your team."]}
                )
            # A prompt report links its chart images instead of uploading them, so it needs no file upload permission.
            if (
                gallery_enabled
                and resource_type != Subscription.ResourceType.AI_PROMPT
                and SlackIntegration(integration).missing_scopes({"files:write"})
            ):
                raise SubscriptionRequestInvalidError(
                    {
                        "delivery_config": [
                            "post_all_insights_in_main_message requires the Slack files:write permission. "
                            "Reconnect Slack to grant it, or remove the option from delivery_config to "
                            "save the subscription now. Each delivery then posts the first image in the "
                            "main message and the rest as threaded replies."
                        ]
                    }
                )

        if gallery_enabled and target_type != Subscription.SubscriptionTarget.SLACK:
            raise SubscriptionRequestInvalidError(
                {
                    "delivery_config": [
                        "post_all_insights_in_main_message only applies to Slack subscriptions. "
                        f"This subscription delivers to {target_type}, so remove it from delivery_config."
                    ]
                }
            )

        prompt_guide = attrs.get("summary_prompt_guide")
        if prompt_guide and len(prompt_guide) > 500:
            raise SubscriptionRequestInvalidError(
                {"summary_prompt_guide": ["AI summary context must be 500 characters or fewer."]}
            )

        if attrs.get("summary_enabled"):
            if not self.organization.is_ai_data_processing_approved:
                raise SubscriptionPermissionDeniedError(
                    "AI data processing must be approved by your organization before enabling AI summaries"
                )

        # Cap gate: fire whenever the row is *becoming* an active summary
        # (summary_enabled=True AND deleted=False) but wasn't before. This
        # catches creates with the toggle on, off→on transitions, AND
        # restoring a soft-deleted summary that was already summary_enabled
        # — otherwise PATCHing `deleted=False` on a grandfathered row would
        # bypass the cap entirely.
        if self._is_becoming_active_summary(attrs):
            self._validate_summary_credit_budget()
            validate_summary_enabled_org_limit(
                self.organization,
                team_id=self.team_id,
                caller_distinct_id=self._caller_distinct_id(),
                is_create=self.instance is None,
            )

        self._check_query_access(attrs, resource_type)

        return attrs

    def _check_query_access(self, attrs: dict, resource_type: str) -> None:
        if resource_type == Subscription.ResourceType.AI_PROMPT:
            return
        subscription_id = self.instance.id if self.instance else None
        if not should_check_table_access(team_id=self.team_id, subscription_id=subscription_id, attrs=attrs):
            return
        # Compiling the queries as the requester needs a real user. The view passes the request's
        # user cast to User, so a synthetic user can still arrive here.
        requester: object = self.user
        if not isinstance(requester, User):
            return
        denied_resources = denied_resources_in_subscription(
            user=requester,
            team=self.team,
            user_access_control=self.viewer,
            subscription_id=subscription_id,
            attrs=attrs,
        )
        if denied_resources:
            denied_names = ", ".join(f"`{name}`" for name in denied_resources)
            raise SubscriptionRequestInvalidError(
                f"Can't save this subscription: you don't have access to {denied_names}."
            )

    def _is_becoming_active_summary(self, attrs: dict) -> bool:
        pre_summary_enabled = self.instance.summary_enabled if self.instance else False
        pre_deleted = self.instance.deleted if self.instance else False
        post_summary_enabled = attrs.get("summary_enabled", pre_summary_enabled)
        post_deleted = attrs.get("deleted", pre_deleted)

        pre_active = pre_summary_enabled and not pre_deleted
        post_active = post_summary_enabled and not post_deleted
        return post_active and not pre_active

    def _validate_summary_credit_budget(self) -> None:
        # Refuse to turn a summary on while the org is over its AI credit budget,
        # mirroring the chat assistant's gate (ee/api/conversation.py).
        if is_team_limited(self.team.api_token, QuotaResource.AI_CREDITS, QuotaLimitingCaches.QUOTA_LIMITER_CACHE_KEY):
            raise SubscriptionQuotaExceededError(
                "Your organization reached its AI credit usage limit. "
                "Increase the limits in Billing settings, or ask an org admin to do so."
            )

    def _validate_dashboard_export_subscription(self, attrs: dict) -> None:
        dashboard = attrs.get("dashboard") or (self.instance.dashboard if self.instance else None)
        if dashboard is None:
            # Reject dashboard_export_insights on non dashboard subscriptions
            if attrs.get("dashboard_export_insights"):
                raise SubscriptionRequestInvalidError(
                    {"dashboard_export_insights": ["Cannot set insights selection without a dashboard."]}
                )
            return

        # For PATCH requests, dashboard_export_insights might not be in attrs - only validate if provided or on create
        dashboard_export_insights_provided = "dashboard_export_insights" in attrs
        dashboard_export_insights = attrs.get("dashboard_export_insights", [])

        is_create = self.instance is None
        if (
            # For new dashboard subscriptions, require at least one insight to be selected
            (is_create and not dashboard_export_insights)
            or
            # If updating and explicitly setting dashboard_export_insights to empty, reject it
            (not is_create and dashboard_export_insights_provided and not dashboard_export_insights)
        ):
            raise SubscriptionRequestInvalidError(
                {"dashboard_export_insights": ["Select at least one insight for this subscription."]}
            )

        if dashboard_export_insights:
            selected_ids = set(dashboard_export_insights)

            if len(selected_ids) > MAX_INSIGHTS:
                raise SubscriptionRequestInvalidError(
                    {"dashboard_export_insights": [f"Cannot select more than {MAX_INSIGHTS} insights."]}
                )

            team_insights = Insight.objects.filter(id__in=selected_ids, team_id=self.team_id)
            viewable_ids = set(viewable_queryset(self.viewer, team_insights, "insight").values_list("id", flat=True))
            unusable_ids = selected_ids - viewable_ids
            if unusable_ids:
                if team_insights.count() != len(selected_ids):
                    raise SubscriptionRequestInvalidError(
                        {"dashboard_export_insights": ["Some insights are not in your team, or no longer exist."]}
                    )
                raise SubscriptionRequestInvalidError(
                    {
                        "dashboard_export_insights": [
                            "Viewer access to every selected insight is required. "
                            "Ask an admin for access, or remove the restricted insights."
                        ]
                    }
                )

            # Ensure all selected insights belong to the dashboard (and are not deleted)
            dashboard_insight_ids = set(
                dashboard.tiles.filter(insight__isnull=False, insight__deleted=False).values_list(
                    "insight_id", flat=True
                )
            )
            invalid_ids = selected_ids - dashboard_insight_ids

            if invalid_ids:
                raise SubscriptionRequestInvalidError(
                    {"dashboard_export_insights": [f"{len(invalid_ids)} invalid insight(s) selected."]}
                )
            return

        if self._keeps_its_own_selection():
            return

        self._require_viewer_access_to_every_live_tile(dashboard)

    def _keeps_its_own_selection(self) -> bool:
        return self.instance is not None and self.instance.dashboard_export_insights.exists()

    def _require_viewer_access_to_every_live_tile(
        self, dashboard: Dashboard, *, error_field: str = "dashboard"
    ) -> None:
        live_tile_insights = Insight.objects.filter(
            team_id=self.team_id,
            id__in=dashboard.tiles.filter(insight__isnull=False, insight__deleted=False).values("insight_id"),
        )
        if blocked_target_ids(self.viewer, live_tile_insights, "insight").exists():
            raise SubscriptionRequestInvalidError(
                {
                    error_field: [
                        "Viewer access to every insight on this dashboard is required. "
                        "Ask an admin for access, or select only the insights you can view."
                    ]
                }
            )

    @staticmethod
    def _context_identifiers(contexts: list[dict[str, Insight | Dashboard]]) -> set[tuple[str, int]]:
        return {(kind, target.id) for context in contexts for kind, target in context.items()}

    @staticmethod
    def _stored_context_identifiers(instance: Subscription) -> set[tuple[str, int]]:
        identifiers: set[tuple[str, int]] = set()
        for context in context_rows(instance):
            if context.dashboard_id is not None:
                identifiers.add(("dashboard", context.dashboard_id))
            elif context.insight_id is not None:
                identifiers.add(("insight", context.insight_id))
        return identifiers

    @staticmethod
    def _replaceable_context_identifiers(instance: Subscription) -> set[tuple[str, int]]:
        identifiers: set[tuple[str, int]] = set()
        for context in context_rows(instance):
            if not context.has_target_for_team(context.team_id, include_deleted=True):
                continue

            if context.dashboard_id is not None:
                identifiers.add(("dashboard", context.dashboard_id))
            elif context.insight_id is not None:
                identifiers.add(("insight", context.insight_id))
        return identifiers

    @staticmethod
    def _context_refs(identifiers: set[tuple[str, int]]) -> list[str]:
        return sorted(context_ref(kind, identifier) for kind, identifier in identifiers)

    @staticmethod
    def _replace_contexts(instance: Subscription, contexts: list[dict[str, Insight | Dashboard]]) -> None:
        context_team_id = instance.team.parent_team_id or instance.team_id
        scoped_contexts = SubscriptionContext.objects.for_team(context_team_id, canonical=True)
        scoped_contexts.filter(subscription=instance).filter(
            Q(dashboard__team_id=context_team_id) | Q(insight__team_id=context_team_id)
        ).delete()
        for context in contexts:
            scoped_contexts.create(team_id=context_team_id, subscription=instance, **context)
        getattr(instance, "_prefetched_objects_cache", {}).pop("contexts", None)

    @staticmethod
    def _save(instance: Subscription, validated_data: dict) -> Subscription:
        for attr, value in validated_data.items():
            setattr(instance, attr, value)
        instance.save()
        return instance

    def _update_with_contexts(
        self,
        instance: Subscription,
        validated_data: dict,
        contexts: list[dict[str, Insight | Dashboard]],
        contexts_in_payload: bool,
        analytics_props: AnalyticsProps,
    ) -> tuple[Subscription, bool]:
        contexts_changed = False
        context_change: tuple[list[str], list[str]] | None = None
        with transaction.atomic():
            if contexts_in_payload:
                instance = Subscription.objects.select_for_update().get(pk=instance.pk)
                stored_identifiers = self._stored_context_identifiers(instance)
                preserved_identifiers = stored_identifiers - self._replaceable_context_identifiers(instance)
                updated_identifiers = preserved_identifiers | self._context_identifiers(contexts)
                contexts_changed = stored_identifiers != updated_identifiers
                if contexts_changed:
                    context_change = (
                        self._context_refs(stored_identifiers),
                        self._context_refs(updated_identifiers),
                    )
            with attribute_subscription_saves(analytics_props, context_change=context_change):
                instance = self._save(instance, validated_data)
            if contexts_changed:
                self._replace_contexts(instance, contexts)
        return instance, contexts_changed

    def create(self, validated_data: dict) -> Subscription:
        validated_data["team_id"] = self.team_id
        validated_data["created_by"] = self.user
        team = self.team
        current_count = Subscription.objects.filter(team_id=team.id, deleted=False).count()
        check_count_limit(
            team=team,
            key=LimitKey.MAX_SUBSCRIPTIONS_PER_TEAM,
            current_count=current_count,
            user=self.user,
        )

        invite_message = validated_data.pop("invite_message", "")
        # The immediate confirmation delivery (SUBSCRIPTION_CHANGE below) is separate from the
        # recurring schedule, which the scheduler drives off next_delivery_date. Creators
        # can opt out of that first send via send_test_now; the schedule is unaffected.
        send_test_now = validated_data.pop("send_test_now", True)
        dashboard_export_insight_ids = validated_data.pop("dashboard_export_insights", [])
        contexts = validated_data.pop("contexts", [])
        with transaction.atomic():
            context_identifiers = self._context_identifiers(contexts)
            context_change: tuple[list[str], list[str]] | None = (
                ([], self._context_refs(context_identifiers)) if context_identifiers else None
            )
            with attribute_subscription_saves(self.analytics_props, context_change=context_change):
                instance: Subscription = Subscription.objects.create(**validated_data)
            self._replace_contexts(instance, contexts)

        # Bust the org-wide active-summary count cache so the next quota
        # fetch reflects this row, regardless of summary_enabled — over-busting
        # is cheap and removes the need to track the prior state.
        invalidate_summary_quota_cache(instance.team.organization_id)

        if dashboard_export_insight_ids:
            instance.dashboard_export_insights.set(dashboard_export_insight_ids)

        if not instance.enabled or not send_test_now:
            return instance

        # The row is committed above and the schedule runs off next_delivery_date, so failing the
        # request here would hide a subscription that exists and make the retry create a second one.
        try:
            with slo_operation(
                spec=SloSpec(
                    distinct_id=str(self.user.distinct_id),
                    area=SloArea.ANALYTIC_PLATFORM,
                    operation=SloOperation.SUBSCRIPTION_CREATE,
                    team_id=instance.team_id,
                    resource_id=str(instance.id),
                ),
                properties={
                    "subscription_id": instance.id,
                    "target_type": instance.target_type,
                    "frequency": instance.frequency,
                    "interval": instance.interval,
                    "byweekday": instance.byweekday,
                    "bysetpos": instance.bysetpos,
                    "count": instance.count,
                    "resource_type": instance.resource_type,
                    "dashboard_export_insights_count": len(dashboard_export_insight_ids),
                    "summary_enabled": instance.summary_enabled,
                    "has_summary_prompt_guide": bool(instance.summary_prompt_guide),
                    "has_until_date": instance.until_date is not None,
                    "has_invite_message": bool(invite_message),
                },
            ):
                temporal = sync_connect()
                workflow_id = f"handle-subscription-value-change-{instance.id}-{uuid.uuid4()}"
                asyncio.run(
                    temporal.start_workflow(
                        "handle-subscription-value-change",
                        ProcessSubscriptionWorkflowInputs(
                            subscription_id=instance.id,
                            team_id=instance.team_id,
                            distinct_id=str(instance.created_by.distinct_id)
                            if instance.created_by
                            else str(instance.team_id),
                            previous_target_value="",
                            previous_value="",
                            invite_message=invite_message,
                            trigger_type=SubscriptionTriggerType.SUBSCRIPTION_CHANGE,
                            resource_type=instance.resource_type,
                        ),
                        id=workflow_id,
                        task_queue=settings.ANALYTICS_PLATFORM_TASK_QUEUE,
                    )
                )
        except Exception as exc:
            _capture_post_write_failure(exc)

        return instance

    def update(self, instance: Subscription, validated_data: dict) -> Subscription:
        previous_target_value = instance.target_value
        was_disabled = instance.enabled is False
        is_delete = not instance.deleted and validated_data.get("deleted") is True
        invite_message = validated_data.pop("invite_message", "")
        # None means "not provided" — the delivery decision then falls back to inferring from
        # what the edit changed, matching the long-standing default behavior.
        send_test_now: bool | None = validated_data.pop("send_test_now", None)
        # Track payload PRESENCE, not truthiness: an empty list (clearing all exports) is delivery-relevant
        # too, so `bool(ids)` would miss it. Pop loses presence, so capture it first.
        export_insights_in_payload = "dashboard_export_insights" in validated_data
        dashboard_export_insight_ids = validated_data.pop("dashboard_export_insights", [])
        contexts_in_payload = "contexts" in validated_data
        contexts = validated_data.pop("contexts", [])
        contexts_changed = False
        analytics_props = self.analytics_props

        # Snapshot delivery-relevant values before the write so the inferred path can tell,
        # after, whether the edit actually changed what gets delivered. Only snapshot the
        # dashboard_export_insights M2M when the payload carries it — that's the only case
        # `.set()` can mutate the relation, so a schedule/meta-only edit pays no M2M query.
        old_delivery_values = {field: getattr(instance, field) for field in self.FIELDS_THAT_TRIGGER_REDELIVERY}
        old_export_insight_ids = (
            set(instance.dashboard_export_insights.values_list("id", flat=True)) if export_insights_in_payload else None
        )

        if is_delete:
            with slo_operation(
                spec=SloSpec(
                    distinct_id=str(self.user.distinct_id),
                    area=SloArea.ANALYTIC_PLATFORM,
                    operation=SloOperation.SUBSCRIPTION_DELETE,
                    team_id=instance.team_id,
                    resource_id=str(instance.id),
                ),
                properties={
                    "subscription_id": instance.id,
                    "target_type": instance.target_type,
                    "frequency": instance.frequency,
                    "resource_type": instance.resource_type,
                },
            ):
                instance, contexts_changed = self._update_with_contexts(
                    instance, validated_data, contexts, contexts_in_payload, analytics_props
                )
            invalidate_summary_quota_cache(instance.team.organization_id)
            return instance

        instance, contexts_changed = self._update_with_contexts(
            instance, validated_data, contexts, contexts_in_payload, analytics_props
        )
        invalidate_summary_quota_cache(instance.team.organization_id)

        # Apply the M2M whenever the field is in the payload — including an empty list, which clears it.
        if export_insights_in_payload:
            instance.dashboard_export_insights.set(dashboard_export_insight_ids)

        is_re_enabling = was_disabled and instance.enabled

        # Re-enabling clears the stale next_delivery_date that was frozen while
        # disabled. Without this, the scheduler picks the sub up on its next tick
        # (the past date matches `next_delivery_date__lte=now`) and fires a second
        # SCHEDULED delivery right after the immediate SUBSCRIPTION_CHANGE confirmation.
        if is_re_enabling:
            instance.set_next_delivery_date()
            instance.save(update_fields=["next_delivery_date"])

        delivery_content_changed = any(
            getattr(instance, field) != old_value for field, old_value in old_delivery_values.items()
        ) or (old_export_insight_ids is not None and set(dashboard_export_insight_ids) != old_export_insight_ids)
        delivery_content_changed = delivery_content_changed or contexts_changed

        # Explicit send_test_now wins. When omitted, infer: send when the edit changed what
        # gets delivered, or on re-enable — a schedule/meta-only edit must not push a fresh
        # delivery. Disabled subscriptions never fire regardless.
        wants_delivery = send_test_now if send_test_now is not None else (is_re_enabling or delivery_content_changed)
        delivery_triggered = wants_delivery and instance.enabled

        # Explicit observability for the delivery decision on edits — the canonical
        # "subscription updated" event fires from the post_save signal before this decision
        # exists, so a regression that silently suppressed deliveries would be invisible there.
        posthoganalytics.capture(
            distinct_id=str(self.user.distinct_id),
            event="subscription_update_delivery_intent",
            properties={
                **analytics_props,
                "subscription_id": instance.id,
                "team_id": instance.team_id,
                "resource_type": instance.resource_type,
                "send_test_now": send_test_now,
                "delivery_triggered": delivery_triggered,
                "re_enabled": is_re_enabling,
                "subscription_enabled": instance.enabled,
            },
            groups=groups(None, instance.team),
        )

        if not delivery_triggered:
            return instance

        if send_test_now:
            # Explicit ask: deterministic ID so a caller spamming send_test_now dedupes to one
            # in-flight delivery per subscription instead of fanning out real sends. Kept distinct
            # from the test-delivery action's ID family so the two flows stay tellable apart.
            workflow_id = f"send-test-now-subscription-{instance.id}"
        else:
            # Inferred delivery (recipient/target change, re-enable): unique ID so two legitimate
            # consecutive edits both deliver instead of the second silently deduping.
            workflow_id = f"handle-subscription-value-change-{instance.id}-{uuid.uuid4()}"
        try:
            temporal = sync_connect()
            asyncio.run(
                temporal.start_workflow(
                    "handle-subscription-value-change",
                    ProcessSubscriptionWorkflowInputs(
                        subscription_id=instance.id,
                        team_id=instance.team_id,
                        distinct_id=str(instance.created_by.distinct_id)
                        if instance.created_by
                        else str(instance.team_id),
                        previous_target_value=previous_target_value,
                        previous_value=previous_target_value,
                        invite_message=invite_message,
                        trigger_type=SubscriptionTriggerType.SUBSCRIPTION_CHANGE,
                        resource_type=instance.resource_type,
                    ),
                    id=workflow_id,
                    task_queue=settings.ANALYTICS_PLATFORM_TASK_QUEUE,
                )
            )
        except WorkflowAlreadyStartedError:
            # A delivery for this subscription is already in flight; the update itself
            # succeeded, so skip the duplicate send rather than failing the request.
            pass
        except Exception as exc:
            _capture_post_write_failure(exc)

        return instance


def create_subscription(
    *,
    team: Team,
    organization: Organization,
    user: User,
    viewer: UserAccessControl,
    write: SubscriptionWrite,
    analytics_props: AnalyticsProps,
) -> SubscriptionRecord:
    subscription_write = _SubscriptionWrite(
        team=team,
        organization=organization,
        user=user,
        viewer=viewer,
        instance=None,
        partial=False,
        is_create_request=True,
        analytics_props=analytics_props,
    )
    validated_data = subscription_write.validate(_write_attrs(write))
    return subscription_record(subscription_write.create(validated_data))


def update_subscription(
    *,
    team: Team,
    organization: Organization,
    user: User,
    viewer: UserAccessControl,
    subscription_id: int,
    write: SubscriptionWrite,
    partial: bool,
    analytics_props: AnalyticsProps,
) -> SubscriptionRecord:
    instance = Subscription.objects.get(pk=subscription_id, team_id=team.id)
    subscription_write = _SubscriptionWrite(
        team=team,
        organization=organization,
        user=user,
        viewer=viewer,
        instance=instance,
        partial=partial,
        is_create_request=False,
        analytics_props=analytics_props,
    )
    validated_data = subscription_write.validate(_write_attrs(write))
    return subscription_record(subscription_write.update(instance, validated_data))


def take_subscription_ownership(
    *,
    team: Team,
    organization: Organization,
    user: User,
    viewer: UserAccessControl,
    subscription_id: int,
    analytics_props: AnalyticsProps,
) -> SubscriptionRecord:
    """Make `user` the owner and enable the subscription, so deliveries run with their access.

    Every refusal comes before the owner changes, so a refused takeover leaves the subscription as
    it was: the new owner must be able to view the dashboard or insight and read every table the
    subscription delivers, and the enable must pass its usual checks as the new owner.
    """
    instance = Subscription.objects.get(pk=subscription_id, team_id=team.id)
    try:
        assert_creator_can_run(user, team, instance.dashboard, instance.insight)
    except (CreatorLeftOrganizationError, UserAccessControlError):
        raise SubscriptionRequestInvalidError("Can't take ownership: you don't have access to this content.") from None
    # The enable below only compiles the queries when it enables a disabled row, so an enabled one is
    # checked here, as the new owner.
    if instance.enabled:
        denied_resources = denied_resources_in_subscription(
            user=user, team=team, user_access_control=viewer, subscription_id=subscription_id, attrs={}
        )
        if denied_resources:
            denied_names = ", ".join(f"`{name}`" for name in denied_resources)
            raise SubscriptionRequestInvalidError(f"Can't take ownership: you don't have access to {denied_names}.")
    # The new owner is set in memory only: the re-enable check reads it off the instance, and the
    # enable's save persists it with `enabled`.
    previous_owner = instance.created_by
    instance.created_by = user
    subscription_write = _SubscriptionWrite(
        team=team,
        organization=organization,
        user=user,
        viewer=viewer,
        instance=instance,
        partial=True,
        is_create_request=False,
        analytics_props=analytics_props,
    )
    validated_data = subscription_write.validate(_write_attrs(SubscriptionWrite(enabled=True)))
    updated = subscription_write.update(instance, validated_data)
    # `created_by` is excluded from the save diff, so the takeover gets its own activity.
    log_activity(
        organization_id=team.organization_id,
        team_id=team.id,
        user=user,
        was_impersonated=get_was_impersonated(),
        item_id=updated.id,
        scope="Subscription",
        activity="took_ownership",
        detail=Detail(
            name=updated.display_name,
            changes=[
                Change(
                    type="Subscription",
                    action="changed",
                    field="created_by",
                    before={"id": previous_owner.id, "email": previous_owner.email} if previous_owner else None,
                    after={"id": user.id, "email": user.email},
                )
            ],
        ),
    )
    return subscription_record(updated)


def start_test_delivery(*, team_id: int, subscription_id: int) -> ManualDeliveryResult:
    subscription = Subscription.objects.get(pk=subscription_id, team_id=team_id)
    temporal = sync_connect()
    workflow_id = f"test-delivery-subscription-{subscription.id}"
    try:
        asyncio.run(
            temporal.start_workflow(
                "handle-subscription-value-change",
                ProcessSubscriptionWorkflowInputs(
                    subscription_id=subscription.id,
                    team_id=subscription.team_id,
                    distinct_id=str(subscription.created_by.distinct_id)
                    if subscription.created_by
                    else str(subscription.team_id),
                    previous_target_value=None,
                    previous_value=None,
                    invite_message=None,
                    trigger_type=SubscriptionTriggerType.MANUAL,
                    resource_type=subscription.resource_type,
                ),
                id=workflow_id,
                task_queue=settings.ANALYTICS_PLATFORM_TASK_QUEUE,
            )
        )
    except WorkflowAlreadyStartedError:
        return ManualDeliveryResult(outcome=ManualDeliveryOutcome.ALREADY_RUNNING, workflow_id=workflow_id)
    except Exception as e:
        capture_exception(e)
        return ManualDeliveryResult(outcome=ManualDeliveryOutcome.FAILED, workflow_id=workflow_id)
    return ManualDeliveryResult(outcome=ManualDeliveryOutcome.STARTED, workflow_id=workflow_id)