: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
from collections.abc import Callable, Iterator, Mapping
from typing import Any
from django.db import transaction
from django.db.models import QuerySet
from products.messaging.backend.models.message_category import MessageCategory, MessageCategoryType
from products.messaging.backend.models.message_preferences import (
ALL_MESSAGE_PREFERENCE_CATEGORY_ID,
MessageRecipientPreference,
PreferenceStatus,
)
from products.messaging.backend.services.opt_out_service import BulkOptOutEntry, BulkOptOutResult, OptOutService
from products.messaging.backend.tasks import sync_preferences_to_customerio_task
class CategoryNotFound(Exception):
pass
def _category(team_id: int, category_key: str) -> MessageCategory:
category = MessageCategory.objects.filter(key=category_key, team_id=team_id).first()
if category is None:
raise CategoryNotFound()
return category
def opted_out(team_id: int, category_key: str | None, search: str | None) -> QuerySet[MessageRecipientPreference]:
# Find recipients who have opted out of this specific category, or use the derived $all category if no specific category is provided
preference_key = str(_category(team_id, category_key).id) if category_key else ALL_MESSAGE_PREFERENCE_CATEGORY_ID
opt_outs = MessageRecipientPreference.objects.filter(
team_id=team_id,
**{f"preferences__{preference_key}": PreferenceStatus.OPTED_OUT.value},
)
if search:
opt_outs = opt_outs.filter(identifier__icontains=search)
return opt_outs.order_by("-updated_at") # Order by most recently updated first
def _sync_after_commit(team_id: int, identifier: str) -> None:
# Customer.io round-trips can take tens of seconds, so sync off the request path
# once the preference write has committed.
transaction.on_commit(lambda: sync_preferences_to_customerio_task.delay(team_id, identifier))
def add_opt_out(
team_id: int, identifier: str, category_key: str | None, created_by_id: int | None
) -> tuple[MessageRecipientPreference, bool]:
category = _category(team_id, category_key) if category_key else None
category_id = str(category.id) if category else ALL_MESSAGE_PREFERENCE_CATEGORY_ID
preference, created = MessageRecipientPreference.objects.get_or_create(
team_id=team_id,
identifier=identifier,
defaults={"created_by_id": created_by_id},
)
preference.set_preference(category_id, PreferenceStatus.OPTED_OUT)
_sync_after_commit(team_id, identifier)
return preference, created
def remove_opt_out(
team_id: int, identifier: str, category_key: str | None, created_by_id: int | None
) -> tuple[MessageRecipientPreference, bool]:
category = _category(team_id, category_key) if category_key else None
preference, created = MessageRecipientPreference.objects.get_or_create(
team_id=team_id,
identifier=identifier,
defaults={"created_by_id": created_by_id},
)
preferences = dict(preference.preferences or {})
if category is None:
preferences[ALL_MESSAGE_PREFERENCE_CATEGORY_ID] = PreferenceStatus.OPTED_IN.value
else:
_lift_global_opt_out(team_id, preferences, category)
preferences[str(category.id)] = PreferenceStatus.OPTED_IN.value
preference.preferences = preferences
preference.save(update_fields=["preferences", "updated_at"])
_sync_after_commit(team_id, identifier)
return preference, created
class TopicsNotFound(Exception):
def __init__(self, keys: list[str]) -> None:
super().__init__(", ".join(keys))
self.keys = keys
def set_preferences(
team_id: int, identifier: str, all_marketing: bool | None, topics: Mapping[str, bool]
) -> dict[str, Any]:
"""Apply `all_marketing`, then each topic in order, in one locked write. Returns the stored preferences.
Raises TopicsNotFound before any write when a topic key names no live category of the team.
"""
categories = {
category.key: category
for category in MessageCategory.objects.filter(team_id=team_id, key__in=list(topics), deleted=False)
}
unknown = [key for key in topics if key not in categories]
if unknown:
raise TopicsNotFound(unknown)
saved: dict[str, Any] = {}
def apply(stored: dict[str, Any]) -> dict[str, Any]:
preferences = dict(stored)
if all_marketing is not None:
preferences[ALL_MESSAGE_PREFERENCE_CATEGORY_ID] = _status(all_marketing)
for key, opted_in in topics.items():
if opted_in:
_lift_global_opt_out(team_id, preferences, categories[key])
preferences[str(categories[key].id)] = _status(opted_in)
saved.update(preferences)
return preferences
transition_preferences(team_id, identifier, apply, touch_updated_at=True)
_sync_after_commit(team_id, identifier)
# The written snapshot, not a reread that a lagging replica could answer with old preferences.
return saved
def _status(opted_in: bool) -> str:
return (PreferenceStatus.OPTED_IN if opted_in else PreferenceStatus.OPTED_OUT).value
def topic_keys_by_id(team_id: int) -> dict[str, str]:
return {
str(category_id): key
for category_id, key in MessageCategory.objects.filter(team_id=team_id, deleted=False).values_list("id", "key")
}
def _lift_global_opt_out(team_id: int, preferences: dict[str, Any], category: MessageCategory) -> None:
"""Clear a `$all` opt-out that would otherwise swallow a per-category resubscribe.
Sends check the category and `$all` together, so opting someone back in to one category
does nothing while `$all` stays opted out. Pin the team's other marketing categories to
opted out first, so lifting `$all` resubscribes only the category the caller named
instead of silently widening consent to everything.
The pinning overwrites even an explicit OPTED_IN on a sibling category (e.g. one a
Customer.io webhook recorded): while `$all` was opted out that opt-in was inert, so
preserving the recipient's effective state means opting the sibling out, not letting
the stale opt-in spring back to life.
"""
if category.category_type != MessageCategoryType.MARKETING:
return
if preferences.get(ALL_MESSAGE_PREFERENCE_CATEGORY_ID) != PreferenceStatus.OPTED_OUT.value:
return
other_category_ids = (
MessageCategory.objects.filter(team_id=team_id, category_type=MessageCategoryType.MARKETING, deleted=False)
.exclude(id=category.id)
.values_list("id", flat=True)
)
for other_category_id in other_category_ids:
preferences[str(other_category_id)] = PreferenceStatus.OPTED_OUT.value
preferences[ALL_MESSAGE_PREFERENCE_CATEGORY_ID] = PreferenceStatus.OPTED_IN.value
def export_rows(team_id: int, category_key: str | None) -> Iterator[str]:
return OptOutService(team_id=team_id).export_rows(category_key)
def bulk_opt_out(
team_id: int, entries: list[BulkOptOutEntry], default_category_key: str | None, created_by_id: int | None
) -> BulkOptOutResult:
return OptOutService(team_id=team_id, created_by_id=created_by_id).opt_out_recipients(entries, default_category_key)
def category_ids(team_id: int) -> set[str]:
return {
str(category_id)
for category_id in MessageCategory.objects.filter(team_id=team_id, deleted=False).values_list("id", flat=True)
}
def marketing_categories(team_id: int) -> QuerySet[MessageCategory]:
return MessageCategory.objects.filter(deleted=False, team=team_id, category_type="marketing").order_by("name")
def get_or_create_recipient(team_id: int, identifier: str) -> MessageRecipientPreference:
recipient, _ = MessageRecipientPreference.objects.get_or_create(team_id=team_id, identifier=identifier)
return recipient
def recipient_or_none(team_id: int, identifier: str) -> MessageRecipientPreference | None:
return MessageRecipientPreference.objects.filter(team_id=team_id, identifier=identifier).first()
def transition_preferences(
team_id: int,
identifier: str,
build: Callable[[dict[str, Any]], dict[str, Any]],
*,
touch_updated_at: bool,
) -> dict[str, Any]:
"""Replace the recipient's preferences with `build(stored)` under a row lock, and return the stored ones.
Concurrent saves for one recipient run one after another, so each sees the result of the one before it.
"""
with transaction.atomic():
MessageRecipientPreference.objects.get_or_create(team_id=team_id, identifier=identifier)
recipient = MessageRecipientPreference.objects.select_for_update().get(team_id=team_id, identifier=identifier)
prior = dict(recipient.preferences or {})
recipient.preferences = build(prior)
recipient.save(update_fields=None if touch_updated_at else ["preferences"])
return prior