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.

31.2 KB
Raw Blame
import sys
from collections.abc import Iterator
from contextlib import contextmanager
from contextvars import ContextVar
from dataclasses import dataclass
from datetime import datetime, timedelta
from typing import TYPE_CHECKING, Any, Literal, Optional, cast
from urllib.parse import urlparse

from django.contrib.postgres.fields import ArrayField
from django.db import models, transaction
from django.db.models.signals import post_save
from django.dispatch import receiver
from django.utils import timezone

from dateutil.rrule import (
    DAILY,
    FR,
    MO,
    MONTHLY,
    SA,
    SU,
    TH,
    TU,
    WE,
    WEEKLY,
    YEARLY,
    rrule,
    weekday as rrule_weekday,
)

from posthog.constants import AvailableFeature
from posthog.event_usage import report_user_action
from posthog.exceptions_capture import capture_exception
from posthog.jwt import PosthogJwtAudience, decode_jwt, encode_jwt
from posthog.models.activity_logging.activity_log import Change, ChangeAction, Detail, changes_between, log_activity
from posthog.models.activity_logging.model_activity import ModelActivityMixin
from posthog.models.signals import model_activity_signal, mutable_receiver
from posthog.models.utils import UUIDModel
from posthog.utils import absolute_uri

if TYPE_CHECKING:
    from posthog.event_usage import AnalyticsProps
    from posthog.models.organization import Organization
    from posthog.models.user import User

    # Resolved lazily via __getattr__ below; declared here so consumers type-check as int.
    SUBSCRIPTION_COUNT_ALLOWED_ON_FREE_TIER: int

UNSUBSCRIBE_TOKEN_EXP_DAYS = 30

# Carries request-derived analytics props (source, referer, ...) into the post_save signal,
# which has no request context. Set by the API layer around request-originated saves so the
# canonical "<kind> subscription created/updated" events get source attribution; stays None
# for system saves (Temporal, management commands), which then report without a source.
subscription_request_analytics_props: ContextVar[Optional["AnalyticsProps"]] = ContextVar(
    "subscription_request_analytics_props", default=None
)
subscription_context_activity_change: ContextVar[tuple[list[str], list[str]] | None] = ContextVar(
    "subscription_context_activity_change", default=None
)


@contextmanager
def attribute_subscription_saves(
    analytics_props: "AnalyticsProps", *, context_change: tuple[list[str], list[str]] | None = None
) -> Iterator[None]:
    analytics_token = subscription_request_analytics_props.set(analytics_props)
    context_token = subscription_context_activity_change.set(context_change)
    try:
        yield
    finally:
        subscription_context_activity_change.reset(context_token)
        subscription_request_analytics_props.reset(analytics_token)


# Single source of truth shared with the frontend create gate via generated schema
# (SubscriptionFreeTierLimit.COUNT). Resolved lazily via PEP 562 so posthog.schema (the
# pydantic models) stays off django.setup(), where this model loads in every process.
def __getattr__(name: str) -> int:
    if name == "SUBSCRIPTION_COUNT_ALLOWED_ON_FREE_TIER":
        from posthog.schema import SubscriptionFreeTierLimit  # noqa: PLC0415

        value = SubscriptionFreeTierLimit.model_fields["root"].default
        # Cache as a real module attribute: later reads skip __getattr__, and tests
        # patching the attribute keep working since mock restores what getattr returns.
        globals()[name] = value
        return value
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")


def _free_tier_subscription_limit() -> int:
    # Module-attribute lookup (not a direct global read) so tests patching
    # SUBSCRIPTION_COUNT_ALLOWED_ON_FREE_TIER on this module still take effect.
    return sys.modules[__name__].SUBSCRIPTION_COUNT_ALLOWED_ON_FREE_TIER


# Max length of the prompt snippet used as an AI subscription's display name when it has no title.
AI_PROMPT_DISPLAY_MAX_LEN = 60

DATEUTIL_WEEKDAY_SHORTHAND_BY_NAME = {
    "monday": MO,
    "tuesday": TU,
    "wednesday": WE,
    "thursday": TH,
    "friday": FR,
    "saturday": SA,
    "sunday": SU,
}

WEEKDAY_SET = {"monday", "tuesday", "wednesday", "thursday", "friday"}


@dataclass
class SubscriptionResource:
    kind: str
    name: str
    url: str


class AIQueryPlanStatus(models.TextChoices):
    FROZEN = "frozen", "Frozen"
    NOT_FROZEN = "not_frozen", "Not frozen"
    PLANNER_UPDATED = "planner_updated", "Planner updated"


class Subscription(ModelActivityMixin, models.Model):
    """
    Rather than re-invent the wheel, we are roughly following the iCalender format for recurring schedules
    https://dateutil.readthedocs.io/en/stable/rrule.html

    Also see https://jakubroztocil.github.io/rrule/ for a helpful visual demonstration
    """

    activity_logging_on_delete = True

    class SubscriptionTarget(models.TextChoices):
        EMAIL = "email"
        SLACK = "slack"
        TEAMS = "teams", "Microsoft Teams"

    class SubscriptionFrequency(models.TextChoices):
        DAILY = "daily"
        WEEKLY = "weekly"
        MONTHLY = "monthly"
        YEARLY = "yearly"

    class SubscriptionByWeekDay(models.TextChoices):
        MONDAY = "monday"
        TUESDAY = "tuesday"
        WEDNESDAY = "wednesday"
        THURSDAY = "thursday"
        FRIDAY = "friday"
        SATURDAY = "saturday"
        SUNDAY = "sunday"

    class ResourceType(models.TextChoices):
        INSIGHT = "insight"
        DASHBOARD = "dashboard"
        AI_PROMPT = "ai_prompt", "AI prompt"

    class AIWindowMode(models.TextChoices):
        SINCE_LAST_SENT = "since_last_sent", "Since last report"
        LAST_N_DAYS = "last_n_days", "Last N days"
        DAYS_AGO_RANGE = "days_ago_range", "Between X and Y days ago"

    RRULE_FIELDS = {"frequency", "count", "interval", "start_date", "until_date", "bysetpos", "byweekday"}

    _FREQ_MAP: dict[str, int] = {
        SubscriptionFrequency.DAILY: DAILY,
        SubscriptionFrequency.WEEKLY: WEEKLY,
        SubscriptionFrequency.MONTHLY: MONTHLY,
        SubscriptionFrequency.YEARLY: YEARLY,
    }

    # Look-back window (in days) an AI report should analyse for each cadence. Unknown
    # frequencies fall back to the weekly window.
    _AI_REPORT_WINDOW_DAYS: dict[str, int] = {
        SubscriptionFrequency.DAILY: 1,
        SubscriptionFrequency.WEEKLY: 7,
        SubscriptionFrequency.MONTHLY: 30,
        SubscriptionFrequency.YEARLY: 365,
    }
    DEFAULT_AI_REPORT_WINDOW_DAYS = 7

    # Relations - i.e. WHAT are we exporting?
    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, related_name="+")
    dashboard = models.ForeignKey("dashboards.Dashboard", on_delete=models.CASCADE, null=True, related_name="+")
    insight = models.ForeignKey("product_analytics.Insight", on_delete=models.CASCADE, null=True, related_name="+")
    dashboard_export_insights = models.ManyToManyField(
        "product_analytics.Insight",
        blank=True,
        related_name="subscriptions_dashboard_export",
    )
    integration = models.ForeignKey(
        "posthog.Integration", on_delete=models.SET_NULL, null=True, blank=True, db_index=False, related_name="+"
    )

    prompt = models.TextField(null=True, blank=True)

    # Frozen by the first successful delivery so later runs reuse the same HogQL deterministically
    # instead of re-running the planner LLM. Edits that require a fresh plan clear it in save().
    # Shape is versioned; see report_pipeline._plan_to_freeze.
    ai_query_plan = models.JSONField(null=True, blank=True, default=None)
    # Source of truth for the shape: products.subscriptions.backend.presentation.views.AIPromptConfigSerializer (writes) and
    # normalize_ai_window below (reads).
    ai_prompt_config = models.JSONField(default=dict, blank=True)

    # Subscription type (email, slack etc.)
    title = models.CharField(max_length=100, null=True, blank=True)
    target_type = models.CharField(max_length=10, choices=SubscriptionTarget)
    target_value = models.TextField()

    # Subscription delivery (related to rrule)
    frequency = models.CharField(max_length=10, choices=SubscriptionFrequency)
    interval = models.IntegerField(default=1)
    count = models.IntegerField(null=True)
    byweekday: ArrayField = ArrayField(
        models.CharField(max_length=10, choices=SubscriptionByWeekDay),
        null=True,
        blank=True,
        default=None,
    )
    bysetpos = models.IntegerField(null=True)
    start_date = models.DateTimeField()
    until_date = models.DateTimeField(null=True, blank=True)

    # Controlled field - next schedule as helper for
    next_delivery_date = models.DateTimeField(null=True, blank=True)

    # Meta
    created_at = models.DateTimeField(auto_now_add=True, blank=True)
    created_by = models.ForeignKey("posthog.User", on_delete=models.SET_NULL, null=True, blank=True, related_name="+")
    deleted = models.BooleanField(default=False)

    # False when paused or auto-disabled because the delivery prerequisite is
    # permanently invalid (e.g. Slack integration disconnected).
    enabled = models.BooleanField(default=True)

    summary_enabled = models.BooleanField(default=False)
    summary_prompt_guide = models.CharField(max_length=500, blank=True, default="")
    delivery_config = models.JSONField(default=dict)

    class Meta:
        indexes = [
            models.Index(fields=["integration"], name="posthog_sub_integration_idx"),
        ]
        db_table = "posthog_subscription"

    def __init__(self, *args: Any, **kwargs: Any) -> None:
        super().__init__(*args, **kwargs)
        # Only cache rrule if all required fields are loaded (not deferred).
        # The rrule property accesses multiple fields (frequency, count, interval, etc).
        # If ANY field is deferred, accessing it triggers refresh_from_db which creates
        # a new instance with OTHER fields deferred, causing infinite recursion.
        if not (self.get_deferred_fields() & self.RRULE_FIELDS):
            self._rrule = self.rrule
        if "prompt" not in self.get_deferred_fields():
            self._initial_prompt = self.prompt
        if "delivery_config" not in self.get_deferred_fields():
            self._initial_include_images = self.includes_delivery_part("include_images")

    def save(self, *args, **kwargs) -> None:
        # Only if the schedule has changed do we update the next delivery date
        # _rrule may not be set if object was loaded with deferred fields
        if not self.id or str(getattr(self, "_rrule", None)) != str(self.rrule):
            self.set_next_delivery_date()
            if "update_fields" in kwargs:
                kwargs["update_fields"].append("next_delivery_date")
        include_images = self.includes_delivery_part("include_images")
        initial_include_images = getattr(self, "_initial_include_images", None)
        if initial_include_images is None and self.id:
            persisted_delivery_config = (
                type(self).objects.filter(id=self.id).values_list("delivery_config", flat=True).first()
            )
            initial_include_images = (
                self._delivery_config_includes(persisted_delivery_config, "include_images")
                if persisted_delivery_config is not None
                else include_images
            )
        prompt_changed = self.prompt != getattr(self, "_initial_prompt", self.prompt)
        images_just_enabled = include_images and not initial_include_images
        # Frozen plans skip chart validation while images are hidden. Enabling images needs a new
        # plan, while feedback and footer options only affect rendering.
        if self.id and (prompt_changed or images_just_enabled) and self.ai_query_plan is not None:
            self.ai_query_plan = None
            if kwargs.get("update_fields") is not None:
                kwargs["update_fields"] = [*kwargs["update_fields"], "ai_query_plan"]
        super().save(*args, **kwargs)
        self._initial_prompt = self.prompt
        self._initial_include_images = include_images

    @staticmethod
    def _delivery_config_includes(delivery_config: Any, option: str) -> bool:
        config = delivery_config if isinstance(delivery_config, dict) else {}
        return bool(config.get(option, True))

    def includes_delivery_part(self, option: str) -> bool:
        return self._delivery_config_includes(self.delivery_config, option)

    def _should_log_activity_for_update(self, **kwargs: Any) -> tuple[bool, Any]:
        should_log, before_update = super()._should_log_activity_for_update(**kwargs)
        return should_log or subscription_context_activity_change.get() is not None, before_update

    @classmethod
    def derive_resource_type(cls, insight_id: int | None, dashboard_id: int | None, prompt: str | None) -> str:
        # Shared by the `resource_type` property and the scheduler's `.values()` fan-out
        # (which has field dicts, not model instances) so the derivation stays single-source.
        if insight_id:
            return cls.ResourceType.INSIGHT
        if dashboard_id:
            return cls.ResourceType.DASHBOARD
        if prompt:
            return cls.ResourceType.AI_PROMPT
        raise ValueError("Subscription has no insight, dashboard, or prompt to derive a resource type from")

    @property
    def resource_type(self) -> str:
        return self.derive_resource_type(self.insight_id, self.dashboard_id, self.prompt)

    @property
    def _has_resource(self) -> bool:
        # Guards url/resource_info from resource_type's raise on a relationless sub.
        return bool(self.insight_id or self.dashboard_id or self.prompt)

    @staticmethod
    def _build_rrule(
        *,
        frequency: str,
        start_date: Any,
        count: Any = None,
        interval: Any = None,
        until_date: Any = None,
        bysetpos: Any = None,
        byweekday: Any = None,
    ) -> rrule:
        freq = cast(Literal[0, 1, 2, 3, 4, 5, 6], Subscription._FREQ_MAP[frequency])
        return rrule(
            freq=freq,
            count=count,
            interval=interval,
            dtstart=start_date,
            until=until_date,
            bysetpos=bysetpos if byweekday and frequency == Subscription.SubscriptionFrequency.MONTHLY else None,
            byweekday=to_rrule_weekdays(byweekday) if byweekday else None,
        )

    @staticmethod
    def _compute_next_delivery_date(*, from_dt: Optional[datetime] = None, **rrule_fields: Any) -> Optional[datetime]:
        interval = rrule_fields.get("interval") or 1
        byweekday = rrule_fields.get("byweekday")
        start_date = rrule_fields.get("start_date")
        if (
            rrule_fields.get("frequency") == Subscription.SubscriptionFrequency.DAILY
            and interval % 7 == 0
            and byweekday
            and start_date
            and start_date.strftime("%A").lower() not in byweekday
        ):
            return None
        # Buffer of 15 minutes since we might run a bit early — never schedule into the past.
        now = timezone.now() + timedelta(minutes=15)
        return Subscription._build_rrule(**rrule_fields).after(dt=max(from_dt or now, now), inc=False)

    @property
    def rrule(self) -> rrule:
        return self._build_rrule(**{f: getattr(self, f) for f in self.RRULE_FIELDS})

    def set_next_delivery_date(self, from_dt: Optional[datetime] = None) -> None:
        # Authoritative schedule — a client-side preview mirror lives in
        # products/subscriptions/frontend/components/Subscriptions/nextDeliveryDate.ts (getNextDeliveryDate).
        self.next_delivery_date = self._compute_next_delivery_date(
            from_dt=from_dt, **{f: getattr(self, f) for f in self.RRULE_FIELDS}
        )

    @classmethod
    def project_next_delivery_date(
        cls, instance: Optional["Subscription"] = None, **overrides: Any
    ) -> Optional[datetime]:
        """What `next_delivery_date` would be for the rrule defined by `instance` fields
        (when given) layered with `overrides`, without persisting. Returns None on an
        exhausted rrule. Pass `instance` for PATCH validation, omit it for creates."""
        base = {f: getattr(instance, f) for f in cls.RRULE_FIELDS} if instance is not None else {}
        merged = {**base, **{k: v for k, v in overrides.items() if k in cls.RRULE_FIELDS}}
        if "frequency" not in merged or "start_date" not in merged:
            return None  # DRF field validation should reject before we get here.
        return cls._compute_next_delivery_date(**merged)

    @classmethod
    def check_subscription_limit(cls, team_id: int, organization: "Organization") -> str | None:
        """Return an error message if the team has reached its subscription limit, else None."""
        feature = organization.get_available_feature(AvailableFeature.SUBSCRIPTIONS)
        # Soft-deleted subscriptions free their slot.
        existing_count = cls.objects.filter(team_id=team_id, deleted=False).count()

        if feature:
            allowed = feature.get("limit")
            # A None limit means unlimited (paid plans without a numeric cap).
            if allowed is not None and existing_count >= allowed:
                return f"Your team has reached the limit of {allowed} subscriptions on your plan."
        else:
            limit = _free_tier_subscription_limit()
            if existing_count >= limit:
                return f"Your plan is limited to {limit} subscriptions."

        return None

    @property
    def ai_report_window_days(self) -> int:
        """Days of history an AI report for this subscription should analyse, derived from its cadence."""
        return self._AI_REPORT_WINDOW_DAYS.get(self.frequency, self.DEFAULT_AI_REPORT_WINDOW_DAYS)

    AI_WINDOW_MAX_DAYS = 365

    @classmethod
    def normalize_ai_window(cls, window: Any) -> dict:
        """Coerce an arbitrary ai_prompt_config["window"] shape to the serializer's contract —
        the JSONField is untyped at runtime, so a row edited out-of-band can carry anything and
        must degrade to the default window instead of crashing reads or delivery runs. Shared by
        the model readers and the API read path."""

        def day_bound(value: Any, minimum: int) -> Optional[int]:
            if isinstance(value, bool) or not isinstance(value, int):
                return None
            return value if minimum <= value <= cls.AI_WINDOW_MAX_DAYS else None

        raw = window if isinstance(window, dict) else {}
        raw_mode = raw.get("mode")
        mode = raw_mode if raw_mode in cls.AIWindowMode.values else cls.AIWindowMode.SINCE_LAST_SENT
        start = day_bound(raw.get("start_days_ago"), 1)
        end = day_bound(raw.get("end_days_ago"), 0)
        # Mirror AIWindowConfigSerializer's per-mode normalisation, so a garbage value in a field
        # the mode ignores can't affect the fields it uses.
        if mode == cls.AIWindowMode.SINCE_LAST_SENT:
            start, end = None, None
        elif mode == cls.AIWindowMode.LAST_N_DAYS:
            end = None
        elif start is not None and end is not None and end >= start:
            start, end = None, None
        return {
            "mode": mode,
            "start_days_ago": start,
            "end_days_ago": end,
        }

    @property
    def _ai_window_config(self) -> dict:
        config = self.ai_prompt_config if isinstance(self.ai_prompt_config, dict) else {}
        return self.normalize_ai_window(config.get("window"))

    @property
    def ai_window_mode(self) -> str:
        return self._ai_window_config["mode"]

    @property
    def ai_window_start_days_ago(self) -> Optional[int]:
        return self._ai_window_config["start_days_ago"]

    @property
    def ai_window_end_days_ago(self) -> Optional[int]:
        return self._ai_window_config["end_days_ago"]

    @property
    def url(self) -> str | None:
        if not self._has_resource:
            return None
        match self.resource_type:
            case self.ResourceType.INSIGHT if self.insight:
                return absolute_uri(f"/insights/{self.insight.short_id}/subscriptions/{self.id}")
            case self.ResourceType.DASHBOARD if self.dashboard:
                return absolute_uri(f"/dashboard/{self.dashboard_id}/subscriptions/{self.id}")
            case self.ResourceType.AI_PROMPT:
                return absolute_uri(f"/project/{self.team_id}/subscriptions/{self.id}")
        return None

    @property
    def resource_info(self) -> Optional[SubscriptionResource]:
        if not self._has_resource:
            return None
        match self.resource_type:
            case self.ResourceType.INSIGHT if self.insight:
                return SubscriptionResource(
                    "Insight",
                    self.insight.name or self.insight.derived_name or "Untitled insight",
                    self.insight.url,
                )
            case self.ResourceType.DASHBOARD if self.dashboard:
                return SubscriptionResource("Dashboard", self.dashboard.name or "Dashboard", self.dashboard.url)
            case self.ResourceType.AI_PROMPT:
                ai_name = self.title or (self.prompt or "").strip()[:AI_PROMPT_DISPLAY_MAX_LEN] or "AI report"
                return SubscriptionResource("AI", ai_name, self.url or "")
        return None

    @property
    def display_name(self) -> str:
        info = self.resource_info
        if info is not None:
            return info.name
        return self.title or "Subscription"

    @property
    def recipient_label(self) -> str:
        """Names the destination in `RecipientResult.recipient` and in the
        `SubscriptionDelivery.target_value` snapshot, both of which the API returns. A webhook URL
        authorizes a post to the channel on its own, so only its host is recorded.
        """
        if self.target_type != self.SubscriptionTarget.TEAMS:
            return self.target_value
        try:
            host = (urlparse(self.target_value).hostname or "").lower()
        except ValueError:
            host = ""
        return host or "webhook"

    @property
    def summary(self) -> str:
        try:
            human_frequency = {
                "daily": "day",
                "weekly": "week",
                "monthly": "month",
                "yearly": "year",
            }[self.frequency]
            if self.interval > 1:
                human_frequency = f"{human_frequency}s"

            summary = f"sent every {str(self.interval) + ' ' if self.interval > 1 else ''}{human_frequency}"

            if self.frequency == self.SubscriptionFrequency.MONTHLY and self.byweekday and self.bysetpos:
                human_bysetpos = {
                    1: "first",
                    2: "second",
                    3: "third",
                    4: "fourth",
                    -1: "last",
                }[self.bysetpos]
                if len(self.byweekday) == 1:
                    day_label = self.byweekday[0].capitalize()
                elif set(self.byweekday) == WEEKDAY_SET:
                    day_label = "weekday"
                else:
                    day_label = "day"
                summary += f" on the {human_bysetpos} {day_label}"
            elif self.byweekday and (
                self.frequency != self.SubscriptionFrequency.DAILY
                or set(self.byweekday) != set(DATEUTIL_WEEKDAY_SHORTHAND_BY_NAME)
            ):
                if set(self.byweekday) == WEEKDAY_SET:
                    summary += " on weekdays"
                else:
                    day_labels = [day.capitalize() for day in self.byweekday]
                    if len(day_labels) == 1:
                        summary += f" on {day_labels[0]}"
                    else:
                        summary += f" on {', '.join(day_labels[:-1])} and {day_labels[-1]}"
            return summary
        except KeyError as e:
            capture_exception(e)
            return "sent on a schedule"

    def get_analytics_metadata(self) -> dict[str, Any]:
        """
        Returns serialized information about the object for analytics reporting.
        """
        metadata: dict[str, Any] = {
            "id": self.id,
            "resource_type": self.resource_type,
            "target_type": self.target_type,
            "num_emails_invited": len(self.target_value.split(",")) if self.target_type == "email" else None,
            "frequency": self.frequency,
            "interval": self.interval,
            "byweekday": self.byweekday,
            "bysetpos": self.bysetpos,
            "prompt_length": len(self.prompt or ""),
            "ai_window_mode": self.ai_window_mode if self.resource_type == self.ResourceType.AI_PROMPT else None,
            "post_all_insights_in_main_message": self.delivery_config.get("post_all_insights_in_main_message", False),
        }
        # For insight subscriptions, attribute the subscribed insight's query type (e.g. TrendsQuery,
        # FunnelsQuery) using the same keys as the "insight created/updated" events, so subscriptions
        # can be sliced by which kinds of insights people subscribe to.
        if self.resource_type == self.ResourceType.INSIGHT and self.insight:
            metadata.update(self.insight.get_analytics_query_kinds())
        return metadata


@receiver(post_save, sender=Subscription, dispatch_uid="hook-subscription-saved")
def subscription_saved(
    sender: type["Subscription"], instance: "Subscription", created: bool, raw: bool, using: str, **kwargs: Any
) -> None:
    # Partial-field saves are internal bookkeeping (e.g. next_delivery_date rescheduling), not a
    # user create/update — a real API save writes the whole row. Skip them so re-enabling or the
    # scheduler doesn't emit a second "<kind> subscription updated" event.
    if kwargs.get("update_fields"):
        return

    resource_info = instance.resource_info
    if instance.created_by and resource_info:
        event_name: str = f"{resource_info.kind.lower()} subscription {'created' if created else 'updated'}"
        user = instance.created_by
        metadata = instance.get_analytics_metadata()
        team = instance.team
        analytics_props = subscription_request_analytics_props.get()

        def capture_subscription_event() -> None:
            report_user_action(
                user,
                event_name,
                metadata,
                team=team,
                analytics_props=analytics_props,
            )

        transaction.on_commit(capture_subscription_event, using=using)


@mutable_receiver(model_activity_signal, sender=Subscription)
def log_subscription_activity(
    sender: type["Subscription"],
    scope: str,
    before_update: Optional["Subscription"],
    after_update: Optional["Subscription"],
    activity: str,
    user: Optional["User"],
    was_impersonated: bool = False,
    **kwargs: Any,
) -> None:
    instance = after_update or before_update
    if instance is None:
        return

    changes = changes_between("Subscription", previous=before_update, current=after_update)
    context_change = subscription_context_activity_change.get()
    if context_change is not None:
        before_contexts, after_contexts = context_change
        action: ChangeAction
        if not before_contexts:
            action = "created"
        elif not after_contexts:
            action = "deleted"
        else:
            action = "changed"
        changes.append(
            Change(
                type="Subscription",
                field="contexts",
                action=action,
                before=before_contexts or None,
                after=after_contexts or None,
            )
        )
    try:
        log_activity(
            organization_id=instance.team.organization_id,
            team_id=instance.team_id,
            user=user,
            was_impersonated=was_impersonated,
            item_id=instance.id,
            scope="Subscription",
            activity=activity,
            detail=Detail(
                name=instance.display_name,
                changes=changes,
            ),
        )
    except Exception as exc:  # never let activity logging break a save
        capture_exception(exc)


def to_rrule_weekdays(weekday: Subscription.SubscriptionByWeekDay) -> set[rrule_weekday]:
    return {DATEUTIL_WEEKDAY_SHORTHAND_BY_NAME[x] for x in weekday}


def get_unsubscribe_token(subscription: Subscription, email: str) -> str:
    return encode_jwt(
        {"id": subscription.id, "email": email},
        expiry_delta=timedelta(days=UNSUBSCRIBE_TOKEN_EXP_DAYS),
        audience=PosthogJwtAudience.UNSUBSCRIBE,
    )


class SubscriptionDelivery(UUIDModel):
    class Status(models.TextChoices):
        STARTING = "starting"
        COMPLETED = "completed"
        FAILED = "failed"
        SKIPPED = "skipped"

    subscription = models.ForeignKey("Subscription", on_delete=models.CASCADE, related_name="deliveries")
    team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, related_name="+")

    # Temporal correlation — workflow_id for debugging, idempotency_key for dedup.
    # idempotency_key is generated via temporalio.workflow.uuid4() which is deterministic
    # across activity retries (replay) but different across workflow retries.
    temporal_workflow_id = models.CharField(max_length=255)
    idempotency_key = models.CharField(max_length=255, unique=True)

    # Trigger context
    trigger_type = models.CharField(max_length=20)
    scheduled_at = models.DateTimeField(null=True)

    # Target snapshot (frozen at delivery time)
    target_type = models.CharField(max_length=10)
    target_value = models.TextField()

    # Content snapshot
    exported_asset_ids: ArrayField = ArrayField(models.IntegerField(), default=list)
    content_snapshot = models.JSONField(default=dict)

    # db_default so workers on the previous image can INSERT without naming this column during a rolling deploy.
    context_refs = ArrayField(models.CharField(max_length=64), default=list, db_default=[])

    # AI-generated summary sent in the delivery, when summary_enabled is on for the subscription.
    # None when no summary is attached.
    change_summary = models.TextField(null=True, blank=True)

    # Per-recipient delivery results
    recipient_results = models.JSONField(default=list)

    # Overall status and error (null when no error)
    # Shape: {"message": str, "type": str, ...} — extensible for stack traces, codes, etc.
    status = models.CharField(max_length=24, choices=Status, default=Status.STARTING)
    error = models.JSONField(null=True, blank=True)

    # Timestamps
    created_at = models.DateTimeField(auto_now_add=True)
    last_updated_at = models.DateTimeField(auto_now=True)
    finished_at = models.DateTimeField(null=True, blank=True)

    class Meta:
        db_table = "posthog_subscription_delivery"
        indexes = [
            models.Index(fields=["subscription", "-created_at"], name="posthog_subdel_sub_crtd"),
            models.Index(fields=["team", "-created_at"], name="posthog_subdel_team_crtd"),
            # Serves the per-run "last successful delivery" anchor lookup.
            models.Index(fields=["subscription", "status", "-finished_at"], name="posthog_subdel_sub_fin"),
        ]
        ordering = ["-created_at"]


def unsubscribe_using_token(token: str) -> Subscription:
    info = decode_jwt(token, audience=PosthogJwtAudience.UNSUBSCRIBE)
    subscription = Subscription.objects.get(pk=info["id"])

    emails = subscription.target_value.split(",")

    if info["email"] in emails:
        emails = [email for email in emails if email != info["email"]]

        subscription.target_value = ",".join(emails)

        if not emails:
            subscription.deleted = True

        subscription.save()

    return subscription