: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
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