Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(backend): keep subscription status and lifecycle dates on the PostHog person (#15040)

Krzysztof Czerwinski7b943729749d
diff --git a/autogpt_platform/backend/backend/copilot/rate_limit.py b/autogpt_platform/backend/backend/copilot/rate_limit.py
index 93b607d890..fae1ff2326 100644
--- a/autogpt_platform/backend/backend/copilot/rate_limit.py
+++ b/autogpt_platform/backend/backend/copilot/rate_limit.py
@@ -64,6 +64,7 @@ from redis.exceptions import RedisClusterException, RedisError
from backend.copilot.trial_cost_context import record_attributed_trial_cost
from backend.data.db_accessors import credit_db, user_db
+from backend.data.posthog_lifecycle_sync import schedule_posthog_lifecycle_sync
from backend.data.redis_client import AsyncRedisClient, get_redis_async
from backend.data.user import get_user_by_id
from backend.util.cache import cached
@@ -1087,6 +1088,7 @@ async def set_user_tier(user_id: str, tier: SubscriptionTier) -> None:
get_user_by_id.cache_delete(user_id) # type: ignore[attr-defined]
get_pending_subscription_change.cache_delete(user_id) # type: ignore[attr-defined]
+ schedule_posthog_lifecycle_sync(user_id)
# Fire-and-forget drift check so admin bulk ops don't wait on Stripe.
asyncio.ensure_future(_drift_check_background(user_id, tier))
diff --git a/autogpt_platform/backend/backend/data/credit.py b/autogpt_platform/backend/backend/data/credit.py
index 9805bb5df6..bb13963843 100644
--- a/autogpt_platform/backend/backend/data/credit.py
+++ b/autogpt_platform/backend/backend/data/credit.py
@@ -36,6 +36,7 @@ from backend.data.model import (
from backend.data.model import User as AppUser
from backend.data.model import UserTransaction
from backend.data.notifications import NotificationEventModel, OpsData
+from backend.data.posthog_lifecycle_sync import schedule_posthog_lifecycle_sync
from backend.data.stripe_client import stripe_call, stripe_list_items
from backend.data.subscription_checkout import (
ensure_no_unconverted_trial,
@@ -1550,6 +1551,8 @@ async def set_auto_top_up(user_id: str, config: AutoTopUpConfig):
async def set_subscription_tier(
user_id: str,
tier: SubscriptionTier,
+ *,
+ track_lifecycle: bool = True,
) -> None:
"""Set the user's subscription tier."""
data: UserUpdateInput = {
@@ -1557,6 +1560,8 @@ async def set_subscription_tier(
}
await User.prisma().update(where={"id": user_id}, data=data)
invalidate_subscription_caches(user_id)
+ if track_lifecycle:
+ schedule_posthog_lifecycle_sync(user_id)
def invalidate_subscription_caches(user_id: str) -> None:
@@ -2695,7 +2700,9 @@ async def _cleanup_stale_subscriptions(customer_id: str, new_sub_id: str) -> Non
)
-async def sync_subscription_from_stripe(stripe_subscription: dict) -> None:
+async def sync_subscription_from_stripe(
+ stripe_subscription: dict, *, track_lifecycle: bool = True
+) -> None:
"""Update User.subscriptionTier from a Stripe subscription object.
Expected shape of stripe_subscription (subset of Stripe's Subscription object):
@@ -2703,7 +2710,22 @@ async def sync_subscription_from_stripe(stripe_subscription: dict) -> None:
status: str — "active" | "trialing" | "canceled" | ...
id: str — Stripe subscription ID
items.data[].price.id: str — Stripe price ID identifying the tier
+
+ Every ``customer.subscription.*`` webhook and every trial transition ends
+ up here, so this is also where the PostHog lifecycle properties are
+ refreshed (in the background, from the customer's current state).
+ ``track_lifecycle=False`` is for the periodic tier sweep, which would
+ otherwise fan out one Stripe call per trial; the daily lifecycle sweep
+ covers those users.
"""
+ await _sync_subscription_tier_from_stripe(stripe_subscription)
+ if track_lifecycle:
+ schedule_posthog_lifecycle_sync(
+ stripe_customer_id=stripe_subscription.get("customer")
+ )
+
+
+async def _sync_subscription_tier_from_stripe(stripe_subscription: dict) -> None:
customer_id = stripe_subscription.get("customer")
if not customer_id:
logger.warning(
@@ -2868,7 +2890,9 @@ async def sync_subscription_from_stripe(stripe_subscription: dict) -> None:
# A future improvement would be to write the new tier first, then
# cancel the old sub.
await _cleanup_stale_subscriptions(customer_id, new_sub_id)
- await set_subscription_tier(user.id, tier)
+ # The wrapper schedules the lifecycle sync (or, for the tier sweep, doesn't),
+ # so the tier write mustn't schedule a second one.
+ await set_subscription_tier(user.id, tier, track_lifecycle=False)
if is_tier_upgrade(current_tier, tier):
billing_cycle = (
metadata.get("billing_cycle") if isinstance(metadata, dict) else None
diff --git a/autogpt_platform/backend/backend/data/credit_subscription_test.py b/autogpt_platform/backend/backend/data/credit_subscription_test.py
index cd95ede498..e27394b5b0 100644
--- a/autogpt_platform/backend/backend/data/credit_subscription_test.py
+++ b/autogpt_platform/backend/backend/data/credit_subscription_test.py
@@ -138,7 +138,9 @@ async def test_sync_subscription_from_stripe_active():
) as mock_set,
):
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.PRO)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.PRO, track_lifecycle=False
+ )
@pytest.mark.asyncio
@@ -232,7 +234,9 @@ async def test_sync_subscription_from_stripe_yearly_pro_maps_to_pro():
) as mock_set,
):
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.PRO)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.PRO, track_lifecycle=False
+ )
@pytest.mark.asyncio
@@ -333,7 +337,9 @@ async def test_sync_subscription_from_stripe_cancelled():
) as mock_set,
):
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.NO_TIER)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.NO_TIER, track_lifecycle=False
+ )
@pytest.mark.asyncio
@@ -367,7 +373,9 @@ async def test_sync_subscription_from_stripe_past_due_downgrades_to_no_tier():
) as mock_set,
):
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.NO_TIER)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.NO_TIER, track_lifecycle=False
+ )
@pytest.mark.asyncio
@@ -389,6 +397,8 @@ async def test_sync_subscription_from_stripe_cancelled_applies_no_tier_storage_l
async def _set_tier(
_user_id: str,
tier: SubscriptionTier,
+ *,
+ track_lifecycle: bool = True,
) -> None:
mock_user.subscriptionTier = tier
@@ -524,7 +534,9 @@ async def test_sync_subscription_from_stripe_trialing():
) as mock_set,
):
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.PRO)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.PRO, track_lifecycle=False
+ )
@pytest.mark.asyncio
@@ -1179,7 +1191,9 @@ async def test_sync_subscription_from_stripe_business_tier():
) as mock_set,
):
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.BUSINESS)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.BUSINESS, track_lifecycle=False
+ )
@pytest.mark.asyncio
@@ -1231,7 +1245,9 @@ async def test_sync_subscription_from_stripe_basic_tier_via_ld_price():
) as mock_set,
):
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.BASIC)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.BASIC, track_lifecycle=False
+ )
@pytest.mark.asyncio
@@ -1286,7 +1302,9 @@ async def test_sync_subscription_from_stripe_cancels_stale_subs():
) as mock_set,
):
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.BUSINESS)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.BUSINESS, track_lifecycle=False
+ )
# Only the stale sub should be cancelled — never the new one.
mock_cancel.assert_called_once_with("sub_old")
@@ -1340,7 +1358,9 @@ async def test_sync_subscription_from_stripe_stale_cancel_errors_swallowed():
):
# Must not raise — tier update proceeds even if cleanup cancel fails.
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.PRO)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.PRO, track_lifecycle=False
+ )
@pytest.mark.asyncio
@@ -1679,7 +1699,9 @@ async def test_sync_subscription_from_stripe_metadata_user_id_matches():
) as mock_set,
):
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.PRO)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.PRO, track_lifecycle=False
+ )
@pytest.mark.asyncio
@@ -1752,7 +1774,9 @@ async def test_sync_subscription_from_stripe_no_metadata_user_id_skips_check():
):
await sync_subscription_from_stripe(stripe_sub)
# No metadata → cross-check skipped → tier updated normally
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.PRO)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.PRO, track_lifecycle=False
+ )
@pytest.mark.asyncio
@@ -3779,7 +3803,9 @@ async def test_sync_subscription_from_stripe_phase_transition_updates_tier():
) as mock_set,
):
await sync_subscription_from_stripe(stripe_sub)
- mock_set.assert_awaited_once_with("user-1", SubscriptionTier.PRO)
+ mock_set.assert_awaited_once_with(
+ "user-1", SubscriptionTier.PRO, track_lifecycle=False
+ )
@pytest.mark.asyncio
diff --git a/autogpt_platform/backend/backend/data/db_manager.py b/autogpt_platform/backend/backend/data/db_manager.py
index 10a550e575..153373e515 100644
--- a/autogpt_platform/backend/backend/data/db_manager.py
+++ b/autogpt_platform/backend/backend/data/db_manager.py
@@ -149,6 +149,7 @@ from backend.data.org_credit import get_org_credits as _get_org_credits_raw
from backend.data.org_credit import get_personal_org_owner
from backend.data.org_credit import spend_org_credits as _spend_org_credits_raw
from backend.data.platform_cost import log_platform_cost
+from backend.data.posthog_lifecycle_sync import start_posthog_lifecycle_sweep
from backend.data.push_subscription import (
cleanup_failed_subscriptions,
delete_push_subscription,
@@ -502,6 +503,7 @@ class DatabaseManager(AppService):
# (scheduler-server, copilot-executor) can self-heal a stale NO_TIER
# row via db_accessors.credit_db() instead of crashing on direct Prisma.
reconcile_stripe_tier_for_user = _(reconcile_stripe_tier_for_user)
+ start_posthog_lifecycle_sweep = _(start_posthog_lifecycle_sweep)
# ============ Platform Linking ============ #
# ============ Orgs ============ #
@@ -942,6 +944,7 @@ class DatabaseManagerAsyncClient(AppServiceClient):
# ============ Subscription Reconciliation ============ #
reconcile_all_stripe_tiers = d.reconcile_all_stripe_tiers
reconcile_stripe_tier_for_user = d.reconcile_stripe_tier_for_user
+ start_posthog_lifecycle_sweep = d.start_posthog_lifecycle_sweep
# ============ Platform Linking ============ #
find_server_link_owner = d.find_server_link_owner
diff --git a/autogpt_platform/backend/backend/data/posthog_lifecycle.py b/autogpt_platform/backend/backend/data/posthog_lifecycle.py
new file mode 100644
index 0000000000..f9b2d2bbc9
--- /dev/null
+++ b/autogpt_platform/backend/backend/data/posthog_lifecycle.py
@@ -0,0 +1,388 @@
+"""Subscription status and lifecycle dates for the PostHog person (SECRT-2778).
+
+This module is the mapping only: pure, no I/O. ``posthog_lifecycle_sync``
+reads the inputs and sends the result.
+
+The status is worked out from the current state every time (the user row,
+the trial row and all of the customer's Stripe subscriptions), never from the
+event that triggered a sync, so an out-of-order webhook can't leave it wrong.
+
+Person properties, set on distinct id = platform user id (dates are ISO-8601
+UTC strings of the real lifecycle moment, never the sync time; a date that
+doesn't apply is ``$unset``, never sent as null):
+
+- ``subscription_status``: one of ``signed``, ``in_trial``,
+ ``trial_canceled``, ``subscribed``, ``subscription_canceled`` (canceled,
+ still active until the period ends), ``payment_failed`` (renewal payment
+ failed; Stripe ``past_due`` or ``unpaid``, access lost),
+ ``subscription_ended``. Rules in
+ ``compute_lifecycle_snapshot``.
+- ``signup_at``: ``User.createdAt``.
+- ``trial_started_at``: ``SubscriptionTrial.startedAt``, for a trial whose
+ checkout completed and wasn't rejected; for a Stripe-native trial (one
+ created outside our trial flow, e.g. in the dashboard), its ``trial_start``.
+- ``subscription_started_at``: start of the current or most recent paid
+ subscription (Stripe ``start_date``); for a converted trial, the conversion
+ (``SubscriptionTrial.convertedAt``).
+- ``subscription_canceled_at``: Stripe ``canceled_at``, while
+ ``subscription_canceled`` or ``subscription_ended``.
+- ``subscription_ended_at``: Stripe ``ended_at``, while ``subscription_ended``.
+"""
+
+from collections.abc import Iterable, Sequence
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from prisma.enums import SubscriptionTier
+from pydantic import BaseModel, Field
+
+from backend.data.subscription_trial import TrialState
+
+LifecycleStatus = Literal[
+ "signed",
+ "in_trial",
+ "trial_canceled",
+ "subscribed",
+ "subscription_canceled",
+ "payment_failed",
+ "subscription_ended",
+]
+
+# Stripe statuses in which a paid subscriber still has a subscription.
+_LIVE_STATUSES = frozenset({"active"})
+# A renewal payment failed. The backend drops the user to NO_TIER, so they have
+# lost access, but they didn't choose to leave (SECRT-2778, question 3).
+_PAYMENT_FAILED_STATUSES = frozenset({"past_due", "unpaid"})
+# A subscription in one of these was never paid for.
+_NEVER_PAID_STATUSES = frozenset({"trialing", "incomplete", "incomplete_expired"})
+_EPOCH = datetime.min.replace(tzinfo=UTC)
+_NEVER = datetime.max.replace(tzinfo=UTC)
+
+
+class StripeSubscriptionFacts(BaseModel):
+ """The fields of a Stripe subscription the mapping reads.
+
+ Validates straight from a Stripe object or dict; Stripe's unix
+ timestamps become UTC datetimes.
+ """
+
+ id: str
+ customer: str | None = None
+ status: str
+ cancel_at_period_end: bool = False
+ start_date: datetime | None = None
+ created: datetime | None = None
+ canceled_at: datetime | None = None
+ ended_at: datetime | None = None
+ trial_start: datetime | None = None
+ trial_end: datetime | None = None
+ metadata: dict[str, str] = Field(default_factory=dict)
+
+ @property
+ def started_at(self) -> datetime | None:
+ return self.start_date or self.created
+
+ @property
+ def trial_enrollment_id(self) -> str | None:
+ return self.metadata.get("trial_enrollment_id") or None
+
+
+class LifecycleUser(BaseModel):
+ id: str
+ created_at: datetime | None = None
+ stripe_customer_id: str | None = None
+ subscription_tier: SubscriptionTier | None = None
+
+
+class LifecycleSnapshot(BaseModel):
+ subscription_status: LifecycleStatus
+ signup_at: datetime | None = None
+ trial_started_at: datetime | None = None
+ subscription_started_at: datetime | None = None
+ subscription_canceled_at: datetime | None = None
+ subscription_ended_at: datetime | None = None
+
+ def person_update(self) -> tuple[dict[str, str], list[str]]:
+ """The ``$set`` and ``$unset`` for this snapshot.
+
+ A date that doesn't apply is unset rather than sent as null, so a
+ value left from an earlier state (say, the end date of a subscription
+ the user has since replaced) can't linger on the person.
+ """
+ dates: dict[str, datetime | None] = self.model_dump(
+ exclude={"subscription_status"}
+ )
+ to_set = {"subscription_status": self.subscription_status}
+ to_set.update({name: _iso(value) for name, value in dates.items() if value})
+ return to_set, [name for name, value in dates.items() if value is None]
+
+
+def compute_lifecycle_snapshot(
+ *,
+ user: LifecycleUser,
+ trial: TrialState | None,
+ subscriptions: Iterable[StripeSubscriptionFacts],
+ now: datetime,
+) -> LifecycleSnapshot:
+ """Map the current state to ``subscription_status`` and its dates.
+
+ First match wins:
+
+ 0. ENTERPRISE (admin-managed, never touched by Stripe) -> ``subscribed``.
+ A live Stripe subscription alongside it still supplies the start date.
+ A self-serve paid tier with no Stripe subscription is not treated as a
+ grant: the column defaulted to PRO from 2026-03-26 to 2026-05-01, so
+ most such rows never paid. They follow the rules below.
+ 1. Live paid subscription set to cancel at period end
+ -> ``subscription_canceled``
+ 2. Live paid subscription (``active``) -> ``subscribed``
+ 3. In trial and set to cancel -> ``trial_canceled``
+ 4. In trial -> ``in_trial``. Our own trial first (including the hour
+ between the trial ending and its first invoice being charged, when
+ Stripe already says ``active`` but the trial hasn't converted), else a
+ Stripe-native ``trialing`` subscription with no trial enrollment.
+ 5. The most recent paid subscription is ``past_due`` or ``unpaid``
+ -> ``payment_failed``
+ 6. A paid subscription that has ended -> ``subscription_ended``
+ 7. A trial that ended without converting -> ``trial_canceled``
+ 8. Otherwise -> ``signed``
+
+ A trial's own Stripe subscription counts as paid only once the trial has
+ converted, and its paid start is then the conversion, not the trial start.
+ The subscription dates belong to the subscription statuses; they are
+ unset in every other status.
+ """
+ tier = SubscriptionTier(user.subscription_tier or SubscriptionTier.NO_TIER)
+ started = _trial_started(trial)
+ all_subs = list(subscriptions)
+ common: dict[str, Any] = {
+ "signup_at": user.created_at,
+ "trial_started_at": (
+ trial.started_at if trial and started else _native_trial_start(all_subs)
+ ),
+ }
+ paid = [sub for sub in all_subs if _is_paid(sub, trial)]
+ live = _current_live(paid)
+
+ if tier == SubscriptionTier.ENTERPRISE:
+ return LifecycleSnapshot(
+ subscription_status="subscribed",
+ subscription_started_at=_paid_start(live, trial) if live else None,
+ **common,
+ )
+ if live is not None:
+ canceling = live.cancel_at_period_end
+ return LifecycleSnapshot(
+ subscription_status="subscription_canceled" if canceling else "subscribed",
+ subscription_started_at=_paid_start(live, trial),
+ subscription_canceled_at=live.canceled_at if canceling else None,
+ **common,
+ )
+ if (
+ trial
+ and started
+ and (_in_trial(trial, now) or _awaiting_conversion(trial, all_subs))
+ ):
+ status = "trial_canceled" if trial.cancel_at_period_end else "in_trial"
+ return LifecycleSnapshot(subscription_status=status, **common)
+ if trial and started and _first_charge_failed(trial, all_subs):
+ return LifecycleSnapshot(subscription_status="payment_failed", **common)
+ native = _native_trial(all_subs, now)
+ if native is not None:
+ status = "trial_canceled" if native.cancel_at_period_end else "in_trial"
+ return LifecycleSnapshot(subscription_status=status, **common)
+ ended_native = any(_is_ended_native_trial(sub, trial) for sub in all_subs)
+ return _after_access_ended(paid, trial, started or ended_native, common)
+
+
+def _is_ended_native_trial(
+ sub: StripeSubscriptionFacts, trial: TrialState | None
+) -> bool:
+ return (
+ not sub.trial_enrollment_id
+ and sub.trial_start is not None
+ and sub.status != "trialing"
+ and not _is_paid(sub, trial)
+ )
+
+
+def _after_access_ended(
+ paid: Sequence[StripeSubscriptionFacts],
+ trial: TrialState | None,
+ trial_started: bool,
+ common: dict[str, Any],
+) -> LifecycleSnapshot:
+ """Rules 5-8: nothing live, no trial running."""
+ ended = max(paid, key=_ended_order, default=None)
+ if ended is not None and ended.status in _PAYMENT_FAILED_STATUSES:
+ return LifecycleSnapshot(
+ subscription_status="payment_failed",
+ subscription_started_at=_paid_start(ended, trial),
+ **common,
+ )
+ if ended is not None:
+ return LifecycleSnapshot(
+ subscription_status="subscription_ended",
+ subscription_started_at=_paid_start(ended, trial),
+ subscription_canceled_at=ended.canceled_at,
+ subscription_ended_at=ended.ended_at,
+ **common,
+ )
+ if trial and trial.converted_at is not None:
+ # The converted subscription is missing from Stripe's list, but the
+ # conversion alone proves a paid subscription existed and has ended.
+ return LifecycleSnapshot(
+ subscription_status="subscription_ended",
+ subscription_started_at=trial.converted_at,
+ **common,
+ )
+ if trial_started:
+ return LifecycleSnapshot(subscription_status="trial_canceled", **common)
+ return LifecycleSnapshot(subscription_status="signed", **common)
+
+
+def _trial_started(trial: TrialState | None) -> bool:
+ """Checkout completed and the offer was not rejected (card reuse etc.)."""
+ return (
+ trial is not None
+ and trial.consumed_at is not None
+ and trial.rejection_reason is None
+ )
+
+
+def _in_trial(trial: TrialState, now: datetime) -> bool:
+ # Not ``TrialState.active``: that is the entitlement check and also needs
+ # a currently verified card. A lapsed card suspends the entitlement, but
+ # the person is still in their trial.
+ return (
+ trial.status == "trialing"
+ and trial.converted_at is None
+ and trial.ends_at is not None
+ and _utc(trial.ends_at) > now
+ )
+
+
+def _awaiting_conversion(
+ trial: TrialState, subscriptions: Sequence[StripeSubscriptionFacts]
+) -> bool:
+ """The trial ended and Stripe made its subscription ``active``, but the
+ first invoice is still a draft (Stripe charges it about an hour later),
+ so the trial hasn't converted yet. A failed charge moves the subscription
+ to ``past_due`` and ends this."""
+ return trial.converted_at is None and any(
+ sub.id == trial.subscription_id
+ and sub.trial_enrollment_id == trial.id
+ and sub.status in _LIVE_STATUSES
+ for sub in subscriptions
+ )
+
+
+def _first_charge_failed(
+ trial: TrialState, subscriptions: Sequence[StripeSubscriptionFacts]
+) -> bool:
+ """The trial's first charge failed and Stripe is still retrying it: the
+ same state the backend reports as ``payment_failed``."""
+ return trial.converted_at is None and any(
+ sub.id == trial.subscription_id
+ and sub.trial_enrollment_id == trial.id
+ and sub.status in _PAYMENT_FAILED_STATUSES
+ for sub in subscriptions
+ )
+
+
+def _is_paid(sub: StripeSubscriptionFacts, trial: TrialState | None) -> bool:
+ if sub.trial_enrollment_id:
+ return (
+ trial is not None
+ and trial.id == sub.trial_enrollment_id
+ and trial.subscription_id == sub.id
+ and trial.converted_at is not None
+ )
+ if sub.status in _NEVER_PAID_STATUSES:
+ return False
+ return not _ended_during_native_trial(sub)
+
+
+def _ended_during_native_trial(sub: StripeSubscriptionFacts) -> bool:
+ """A Stripe-native trial canceled before its first charge was never paid."""
+ ended = sub.ended_at or sub.canceled_at
+ return (
+ sub.trial_end is not None
+ and sub.status not in _LIVE_STATUSES
+ and ended is not None
+ and _utc(ended) <= _utc(sub.trial_end)
+ )
+
+
+def _current_live(
+ paid: Sequence[StripeSubscriptionFacts],
+) -> StripeSubscriptionFacts | None:
+ # Normally at most one. If there are two, the one not being canceled is
+ # the subscription the user is keeping.
+ return max(
+ (sub for sub in paid if sub.status in _LIVE_STATUSES),
+ key=lambda sub: (not sub.cancel_at_period_end, _utc(sub.started_at)),
+ default=None,
+ )
+
+
+def _native_trial(
+ subscriptions: Sequence[StripeSubscriptionFacts], now: datetime
+) -> StripeSubscriptionFacts | None:
+ """A running Stripe trial that didn't come through our trial flow."""
+ return max(
+ (
+ sub
+ for sub in subscriptions
+ if sub.status == "trialing"
+ and not sub.trial_enrollment_id
+ and (sub.trial_end is None or _utc(sub.trial_end) > now)
+ ),
+ key=lambda sub: _utc(sub.started_at),
+ default=None,
+ )
+
+
+def _ended_order(sub: StripeSubscriptionFacts) -> tuple[datetime, datetime]:
+ # The most recently started subscription is the one the user is on. Not
+ # the end date: after an upgrade the old subscription is canceled after
+ # the new one started. Ties go to the one that ended last, and a failed
+ # renewal hasn't ended. Known gap: an older subscription that outlived a
+ # newer one loses to it; Stripe data alone can't tell which one the user
+ # kept using.
+ failed = sub.status in _PAYMENT_FAILED_STATUSES
+ return (
+ _utc(sub.started_at),
+ _NEVER if failed else _utc(sub.ended_at or sub.canceled_at),
+ )
+
+
+def _native_trial_start(
+ subscriptions: Sequence[StripeSubscriptionFacts],
+) -> datetime | None:
+ """Start of the newest Stripe-native trial (one outside our trial flow),
+ kept after it converts or ends, as our own trial's start is."""
+ native = max(
+ (s for s in subscriptions if not s.trial_enrollment_id and s.trial_start),
+ key=lambda s: _utc(s.trial_start),
+ default=None,
+ )
+ return native.trial_start if native else None
+
+
+def _paid_start(
+ sub: StripeSubscriptionFacts, trial: TrialState | None
+) -> datetime | None:
+ if sub.trial_enrollment_id and trial is not None and trial.converted_at:
+ return trial.converted_at
+ return sub.started_at
+
+
+def _utc(value: datetime | None) -> datetime:
+ if value is None:
+ return _EPOCH
+ return value.replace(tzinfo=UTC) if value.tzinfo is None else value
+
+
+def _iso(value: datetime) -> str:
+ return _utc(value).astimezone(UTC).isoformat(timespec="seconds")
diff --git a/autogpt_platform/backend/backend/data/posthog_lifecycle_hooks_test.py b/autogpt_platform/backend/backend/data/posthog_lifecycle_hooks_test.py
new file mode 100644
index 0000000000..b67b7e223f
--- /dev/null
+++ b/autogpt_platform/backend/backend/data/posthog_lifecycle_hooks_test.py
@@ -0,0 +1,227 @@
+"""Every write that can change a user's lifecycle snapshot schedules a sync,
+and a PostHog or Stripe failure in that sync never reaches the caller."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+import stripe
+from prisma.enums import SubscriptionTier
+
+from backend.copilot.rate_limit import set_user_tier
+from backend.data import posthog_lifecycle_sync as lifecycle
+from backend.data import user as user_module
+from backend.data.credit import set_subscription_tier, sync_subscription_from_stripe
+from backend.data.stripe_reconciliation import _collect_status_page
+
+TRIAL_SUB = {
+ "id": "sub_trial",
+ "customer": "cus_1",
+ "status": "trialing",
+ "metadata": {"user_id": "user-1", "trial_enrollment_id": "trial-1"},
+}
+
+
+async def test_subscription_sync_schedules_by_customer():
+ with (
+ patch(
+ "backend.data.credit._sync_subscription_tier_from_stripe",
+ new_callable=AsyncMock,
+ ) as inner,
+ patch("backend.data.credit.schedule_posthog_lifecycle_sync") as schedule,
+ ):
+ await sync_subscription_from_stripe(TRIAL_SUB)
+
+ inner.assert_awaited_once_with(TRIAL_SUB)
+ schedule.assert_called_once_with(stripe_customer_id="cus_1")
+
+
+async def test_a_tier_change_honours_track_lifecycle_false():
+ """The tier sweep's opt-out must reach set_subscription_tier too, or a
+ tier change inside the sweep schedules a sync anyway."""
+ update = AsyncMock()
+ with (
+ patch(
+ "backend.data.credit.User.prisma",
+ return_value=MagicMock(update=update),
+ ),
+ patch("backend.data.credit.invalidate_subscription_caches"),
+ patch("backend.data.credit.schedule_posthog_lifecycle_sync") as schedule,
+ ):
+ await set_subscription_tier(
+ "user-1", SubscriptionTier.PRO, track_lifecycle=False
+ )
+ schedule.assert_not_called()
+ await set_subscription_tier("user-1", SubscriptionTier.PRO)
+ schedule.assert_called_once_with("user-1")
+ assert update.await_count == 2
+
+
+async def test_tier_sweep_does_not_schedule_lifecycle_syncs():
+ """The 6-hourly tier sweep re-syncs every trial; scheduling from there
+ would fan out one Stripe call per trial and could rate-limit the sweep's
+ own listing. The daily lifecycle sweep covers those users."""
+ page = MagicMock(
+ data=[stripe.Subscription.construct_from(TRIAL_SUB, "k")], has_more=False
+ )
+ user = MagicMock(subscriptionTier=SubscriptionTier.TRIAL)
+ with (
+ patch(
+ "backend.data.stripe_reconciliation.stripe.Subscription.list_async",
+ new_callable=AsyncMock,
+ return_value=page,
+ ),
+ patch(
+ "backend.data.credit._sync_subscription_tier_from_stripe",
+ new_callable=AsyncMock,
+ ) as inner,
+ patch(
+ "backend.data.stripe_reconciliation.User.prisma",
+ return_value=MagicMock(find_first=AsyncMock(return_value=user)),
+ ),
+ patch("backend.data.credit.schedule_posthog_lifecycle_sync") as schedule,
+ ):
+ tiers: dict[str, SubscriptionTier] = {}
+ incomplete = await _collect_status_page("trialing", {}, tiers)
+
+ assert incomplete is False
+ inner.assert_awaited_once()
+ schedule.assert_not_called()
+ assert tiers == {"cus_1": SubscriptionTier.TRIAL}
+
+
+async def test_failed_subscription_sync_raises_as_before_and_schedules_nothing():
+ with (
+ patch(
+ "backend.data.credit._sync_subscription_tier_from_stripe",
+ new_callable=AsyncMock,
+ side_effect=ValueError("no enrollment"),
+ ),
+ patch("backend.data.credit.schedule_posthog_lifecycle_sync") as schedule,
+ ):
+ with pytest.raises(ValueError):
+ await sync_subscription_from_stripe(TRIAL_SUB)
+ schedule.assert_not_called()
+
+
+async def test_trial_transitions_schedule_through_the_webhook_choke_point():
+ """Trial start, cancel, conversion and expiry are all written by
+ ``reconcile_trial_subscription``, which only runs inside
+ ``sync_subscription_from_stripe``; its early return still schedules."""
+ user = MagicMock(id="user-1", subscriptionTier=SubscriptionTier.NO_TIER)
+ with (
+ patch(
+ "backend.data.credit.User.prisma",
+ return_value=MagicMock(find_first=AsyncMock(return_value=user)),
+ ),
+ patch(
+ "backend.data.credit.reconcile_trial_subscription",
+ new_callable=AsyncMock,
+ return_value=(TRIAL_SUB, SubscriptionTier.TRIAL),
+ ) as reconcile,
+ patch("backend.data.credit.invalidate_subscription_caches"),
+ patch("backend.data.credit.schedule_posthog_lifecycle_sync") as schedule,
+ ):
+ await sync_subscription_from_stripe(TRIAL_SUB)
+
+ reconcile.assert_awaited_once_with("user-1", "sub_trial")
+ schedule.assert_called_once_with(stripe_customer_id="cus_1")
+
+
+async def test_webhook_survives_posthog_and_stripe_failures():
+ """The real scheduler, with the sync's Stripe read and PostHog send both
+ failing: the webhook returns normally and the failure stays in the
+ background task."""
+ client = MagicMock()
+ client.capture.side_effect = RuntimeError("posthog down")
+ user_row = MagicMock(
+ id="user-1",
+ createdAt=None,
+ stripeCustomerId="cus_1",
+ subscriptionTier=SubscriptionTier.PRO,
+ subscriptionTrial=None,
+ )
+ lifecycle_prisma = MagicMock(
+ find_first=AsyncMock(return_value=user_row),
+ find_unique=AsyncMock(return_value=user_row),
+ )
+ lifecycle._syncs.clear()
+ with (
+ patch(
+ "backend.data.credit._sync_subscription_tier_from_stripe",
+ new_callable=AsyncMock,
+ ),
+ patch(
+ "backend.data.posthog_lifecycle_sync.get_posthog_client",
+ return_value=client,
+ ),
+ patch(
+ "backend.data.posthog_lifecycle_sync.User.prisma",
+ return_value=lifecycle_prisma,
+ ),
+ patch.object(
+ stripe.Subscription,
+ "list_async",
+ AsyncMock(side_effect=stripe.APIConnectionError("stripe down")),
+ ),
+ ):
+ await sync_subscription_from_stripe(TRIAL_SUB)
+ while lifecycle._background_tasks:
+ await asyncio.gather(*list(lifecycle._background_tasks))
+ await asyncio.sleep(0)
+
+ client.capture.assert_not_called()
+
+
+async def test_tier_change_schedules_the_user():
+ with (
+ patch(
+ "backend.data.credit.User.prisma",
+ return_value=MagicMock(update=AsyncMock()),
+ ),
+ patch("backend.data.credit.invalidate_subscription_caches"),
+ patch("backend.data.credit.schedule_posthog_lifecycle_sync") as schedule,
+ ):
+ await set_subscription_tier("user-1", SubscriptionTier.PRO)
+ schedule.assert_called_once_with("user-1")
+
+
+async def test_admin_tier_override_schedules_the_user():
+ with (
+ patch(
+ "backend.copilot.rate_limit.PrismaUser.prisma",
+ return_value=MagicMock(update=AsyncMock()),
+ ),
+ patch("backend.copilot.rate_limit._drift_check_background", new=AsyncMock()),
+ patch("backend.copilot.rate_limit.get_user_tier", new=MagicMock()),
+ patch("backend.copilot.rate_limit.get_user_by_id", new=MagicMock()),
+ patch("backend.data.credit.get_pending_subscription_change", new=MagicMock()),
+ patch("backend.copilot.rate_limit.schedule_posthog_lifecycle_sync") as schedule,
+ ):
+ await set_user_tier("user-1", SubscriptionTier.ENTERPRISE)
+ schedule.assert_called_once_with("user-1")
+
+
[email protected]("existing", [False, True])
+async def test_signup_schedules_only_a_new_user(existing: bool):
+ db_user = MagicMock(id="user-1", email="[email protected]", name=None)
+ app_user = MagicMock(id="user-1")
+ with (
+ patch.object(user_module, "prisma") as prisma,
+ patch.object(user_module, "_ensure_user_profile", new_callable=AsyncMock),
+ patch.object(user_module, "ensure_personal_org", new_callable=AsyncMock),
+ patch.object(user_module.User, "from_db", return_value=app_user),
+ patch.object(user_module, "UserCreationResult") as result,
+ patch.object(user_module, "schedule_posthog_lifecycle_sync") as schedule,
+ ):
+ prisma.user.find_unique = AsyncMock(return_value=db_user if existing else None)
+ prisma.user.create = AsyncMock(return_value=db_user)
+ await user_module.get_or_create_user_with_status(
+ {"sub": "user-1", "email": "[email protected]"}
+ )
+
+ result.assert_called_once()
+ if existing:
+ schedule.assert_not_called()
+ else:
+ schedule.assert_called_once_with("user-1")
diff --git a/autogpt_platform/backend/backend/data/posthog_lifecycle_sync.py b/autogpt_platform/backend/backend/data/posthog_lifecycle_sync.py
new file mode 100644
index 0000000000..874763b7e3
--- /dev/null
+++ b/autogpt_platform/backend/backend/data/posthog_lifecycle_sync.py
@@ -0,0 +1,420 @@
+"""Keep subscription status and lifecycle dates on the PostHog person.
+
+These are person properties, not events: each sync sends one ``$set`` on the
+platform user id, the same id the browser passes to ``identify``, so they land
+on the canonical person. The mapping itself is ``posthog_lifecycle``.
+
+Three ways in, all best-effort (a failure is logged, never raised):
+
+- ``schedule_posthog_lifecycle_sync`` after a write that can change the
+ snapshot (signup, tier changes, ``sync_subscription_from_stripe``). It runs
+ in the background, so a webhook or a signup never waits on Stripe or
+ PostHog.
+- ``sync_all_posthog_lifecycles``, daily from the scheduler: the safety net
+ for a missed hook and for a trial that runs out on the clock.
+- ``scripts/backfill_posthog_lifecycle.py``, the same sweep run by hand.
+"""
+
+import asyncio
+import logging
+import weakref
+from collections import Counter
+from collections.abc import Coroutine, Sequence
+from datetime import UTC, datetime
+from typing import Any
+
+import stripe
+from prisma.models import SubscriptionTrial, User
+from pydantic import BaseModel
+
+from backend.data.db import query_raw_with_schema
+from backend.data.posthog_lifecycle import (
+ LifecycleSnapshot,
+ LifecycleUser,
+ StripeSubscriptionFacts,
+ compute_lifecycle_snapshot,
+)
+from backend.data.stripe_client import stripe_call, stripe_list_items
+from backend.data.subscription_trial import TrialState
+from backend.util.posthog_client import get_posthog_client
+from backend.util.posthog_events import PostHogEvent
+
+logger = logging.getLogger(__name__)
+
+_SYNC_TIMEOUT_SECONDS = 60
+_MAX_CONCURRENT_SYNCS = 4
+
+
+def schedule_posthog_lifecycle_sync(
+ user_id: str | None = None, *, stripe_customer_id: str | None = None
+) -> None:
+ """Sync one user in the background, after the caller's write.
+
+ Never raises and never makes the caller wait. Pass the user id, or the
+ Stripe customer id when that is all the caller has; a customer id is
+ resolved to its user first, so both end up coordinated per user:
+
+ - a sync that is queued and hasn't started covers this call, because it
+ reads the state when it starts;
+ - a sync that is already running is followed by exactly one more, so the
+ last one sent always read the state after this write;
+ - two syncs for one user never run at the same time in this process, so
+ an older read can't be sent after a newer one here. Another pod, or the
+ daily sweep (which reads Stripe once at its start), can still send an
+ older read; the next sync or sweep corrects it.
+ """
+ try:
+ if get_posthog_client() is None:
+ return
+ if user_id:
+ _schedule_user(user_id)
+ elif stripe_customer_id:
+ _spawn(_resolve_customer(stripe_customer_id))
+ except Exception:
+ logger.warning("Failed to schedule a lifecycle sync", exc_info=True)
+
+
+# Per user id: "queued", "running", or "rerun" (running, then run once more).
+_syncs: dict[str, str] = {}
+_background_tasks: set[asyncio.Task] = set()
+# One per event loop: an asyncio.Semaphore binds to the loop it is first used in.
+_slots: "weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, asyncio.Semaphore]" = (
+ weakref.WeakKeyDictionary()
+)
+
+
+def _schedule_user(user_id: str) -> None:
+ state = _syncs.get(user_id)
+ if state == "running":
+ _syncs[user_id] = "rerun"
+ elif state is None:
+ _spawn(_run_user_sync(user_id))
+ _syncs[user_id] = "queued"
+
+
+def _spawn(coro: Coroutine[Any, Any, None]) -> None:
+ try:
+ task = asyncio.get_running_loop().create_task(coro)
+ except RuntimeError:
+ coro.close()
+ raise
+ _background_tasks.add(task)
+ task.add_done_callback(_background_tasks.discard)
+
+
+async def _resolve_customer(stripe_customer_id: str) -> None:
+ try:
+ user = await User.prisma().find_first(
+ where={"stripeCustomerId": stripe_customer_id}
+ )
+ if user is not None:
+ _schedule_user(user.id)
+ except Exception:
+ logger.warning(
+ f"Lifecycle sync: can't resolve customer {stripe_customer_id}",
+ exc_info=True,
+ )
+
+
+async def _run_user_sync(user_id: str) -> None:
+ # Cleanup wraps the slot as well: a task cancelled while waiting for a
+ # slot must not leave its entry behind, or every later request for this
+ # user would see "queued" and never run.
+ cancelled = False
+ try:
+ # Bounded so a burst of hooks can't fan out into a burst of Stripe
+ # calls that rate-limits the billing code sharing the Stripe account.
+ async with _sync_slot():
+ while True:
+ _syncs[user_id] = "running"
+ try:
+ await asyncio.wait_for(
+ sync_posthog_lifecycle(user_id), timeout=_SYNC_TIMEOUT_SECONDS
+ )
+ except Exception:
+ logger.warning(
+ f"Lifecycle sync failed for user {user_id}", exc_info=True
+ )
+ if _syncs.get(user_id) != "rerun":
+ return
+ except asyncio.CancelledError:
+ cancelled = True
+ raise
+ finally:
+ state = _syncs.pop(user_id, None)
+ if cancelled and state in ("queued", "rerun"):
+ # Requests absorbed by this task would otherwise be lost.
+ _requeue(user_id)
+
+
+def _requeue(user_id: str) -> None:
+ try:
+ _schedule_user(user_id)
+ except Exception:
+ logger.warning(f"Lifecycle sync: can't requeue user {user_id}", exc_info=True)
+
+
+def _sync_slot() -> asyncio.Semaphore:
+ loop = asyncio.get_running_loop()
+ slot = _slots.get(loop)
+ if slot is None:
+ slot = _slots[loop] = asyncio.Semaphore(_MAX_CONCURRENT_SYNCS)
+ return slot
+
+
+async def sync_posthog_lifecycle(
+ user_id: str,
+ *,
+ stripe_subscriptions: Sequence[StripeSubscriptionFacts] | None = None,
+) -> LifecycleSnapshot | None:
+ """Send the user's current lifecycle snapshot. Never raises.
+
+ ``stripe_subscriptions`` is the customer's complete list, for a caller
+ that already has it. Otherwise it is read from Stripe, and only for a
+ user with a Stripe customer. A webhook payload is deliberately not used
+ in its place: it is one subscription as of one event, which is exactly
+ the "last event received" the status must not depend on.
+ """
+ try:
+ if not user_id or get_posthog_client() is None:
+ return None
+ snapshot = await load_lifecycle_snapshot(
+ user_id, stripe_subscriptions=stripe_subscriptions
+ )
+ if snapshot is not None:
+ send_lifecycle_snapshot(user_id, snapshot)
+ return snapshot
+ except Exception:
+ logger.warning(
+ f"Failed to sync lifecycle properties for user {user_id}", exc_info=True
+ )
+ return None
+
+
+async def load_lifecycle_snapshot(
+ user_id: str,
+ *,
+ stripe_subscriptions: Sequence[StripeSubscriptionFacts] | None = None,
+ now: datetime | None = None,
+) -> LifecycleSnapshot | None:
+ """Read the user's current state and map it. None if the user is gone."""
+ row = await User.prisma().find_unique(
+ where={"id": user_id}, include={"subscriptionTrial": True}
+ )
+ if row is None:
+ return None
+ if stripe_subscriptions is None:
+ stripe_subscriptions = (
+ await list_customer_subscriptions(row.stripeCustomerId)
+ if row.stripeCustomerId
+ else []
+ )
+ trial_row = row.subscriptionTrial
+ return compute_lifecycle_snapshot(
+ user=LifecycleUser(
+ id=row.id,
+ created_at=row.createdAt,
+ stripe_customer_id=row.stripeCustomerId,
+ subscription_tier=row.subscriptionTier,
+ ),
+ trial=TrialState.from_db(trial_row) if trial_row else None,
+ subscriptions=stripe_subscriptions,
+ now=now or datetime.now(UTC),
+ )
+
+
+async def list_customer_subscriptions(
+ customer_id: str,
+) -> list[StripeSubscriptionFacts]:
+ page = await stripe_call(
+ stripe.Subscription.list_async, customer=customer_id, status="all", limit=100
+ )
+ return [
+ StripeSubscriptionFacts.model_validate(sub)
+ async for sub in stripe_list_items(page)
+ ]
+
+
+def send_lifecycle_snapshot(user_id: str, snapshot: LifecycleSnapshot) -> bool:
+ """Queue the ``$set``. False when analytics is off or queueing failed."""
+ try:
+ client = get_posthog_client()
+ if not user_id or client is None:
+ return False
+ to_set, to_unset = snapshot.person_update()
+ properties: dict[str, object] = {"$set": to_set}
+ if to_unset:
+ properties["$unset"] = to_unset
+ client.capture(
+ PostHogEvent.SET_PERSON_PROPERTIES.value,
+ distinct_id=user_id,
+ properties=properties,
+ )
+ return True
+ except Exception:
+ logger.warning(
+ f"Failed to send lifecycle properties for user {user_id}", exc_info=True
+ )
+ return False
+
+
+async def start_posthog_lifecycle_sweep() -> bool:
+ """Start the daily sweep in the background and return at once.
+
+ The scheduler reaches this over RPC, whose call timeout is shorter than a
+ large sweep can take and which retries on a timeout; waiting for the sweep
+ there would start a second one alongside the first. Returns False when a
+ sweep is already running in this process.
+ """
+ if any(not task.done() for task in _sweeps):
+ return False
+ task = asyncio.get_running_loop().create_task(_run_sweep())
+ _sweeps.add(task)
+ task.add_done_callback(_sweeps.discard)
+ return True
+
+
+_sweeps: set[asyncio.Task] = set()
+
+
+async def _run_sweep() -> None:
+ try:
+ summary = await sync_all_posthog_lifecycles()
+ except Exception:
+ logger.exception("Lifecycle sweep failed")
+ return
+ if summary.aborted:
+ logger.warning(f"Lifecycle sweep aborted: {summary.aborted}")
+
+
+class LifecycleSyncSummary(BaseModel):
+ dry_run: bool
+ stripe_subscriptions: int = 0
+ users: int = 0
+ sent: int = 0
+ errors: int = 0
+ status_counts: dict[str, int] = {}
+ aborted: str | None = None
+
+
+async def sync_all_posthog_lifecycles(
+ *,
+ dry_run: bool = False,
+ all_users: bool = False,
+ batch_size: int = 500,
+ now: datetime | None = None,
+) -> LifecycleSyncSummary:
+ """Recompute and send the snapshot of every user with billing history.
+
+ Billing history means a Stripe customer or a trial row; ``all_users``
+ widens it to everyone (a ``signed`` user gets ``signup_at`` and the
+ status). Stripe is read once, as a full ``Subscription.list(status=all)``,
+ not per user. A failed listing aborts the run: a partial list would mark
+ people whose subscriptions sit on the missing pages as ``signed``.
+
+ Sends are flushed after each batch so a large run can't overflow the
+ PostHog client's in-memory queue, which drops events once it is full.
+ """
+ summary = LifecycleSyncSummary(dry_run=dry_run)
+ client = None if dry_run else get_posthog_client()
+ if not dry_run and client is None:
+ summary.aborted = "PostHog is not configured"
+ return summary
+ try:
+ by_customer = await _all_subscriptions_by_customer()
+ except Exception:
+ logger.exception("Lifecycle sync: listing Stripe subscriptions failed")
+ summary.aborted = "Stripe listing failed"
+ return summary
+ summary.stripe_subscriptions = sum(len(subs) for subs in by_customer.values())
+ counts: Counter[str] = Counter()
+ after_id = ""
+ while users := await _lifecycle_user_batch(after_id, batch_size, all_users):
+ await _sync_batch(users, by_customer, now or datetime.now(UTC), summary, counts)
+ after_id = users[-1].id
+ if client is not None:
+ await asyncio.to_thread(client.flush)
+ summary.status_counts = dict(sorted(counts.items()))
+ logger.info(f"Lifecycle sync finished: {summary.model_dump_json()}")
+ return summary
+
+
+async def _sync_batch(
+ users: list[LifecycleUser],
+ by_customer: dict[str, list[StripeSubscriptionFacts]],
+ now: datetime,
+ summary: LifecycleSyncSummary,
+ counts: Counter[str],
+) -> None:
+ trials = await _trials_by_user([user.id for user in users])
+ for user in users:
+ summary.users += 1
+ try:
+ if user.id in trials and trials[user.id] is None:
+ # Mapping without the trial would call them ``signed``.
+ raise ValueError("unreadable trial row")
+ snapshot = compute_lifecycle_snapshot(
+ user=user,
+ trial=trials.get(user.id),
+ subscriptions=by_customer.get(user.stripe_customer_id or "", []),
+ now=now,
+ )
+ except Exception:
+ summary.errors += 1
+ logger.warning(f"Lifecycle sync: can't map user {user.id}", exc_info=True)
+ continue
+ counts[snapshot.subscription_status] += 1
+ if summary.dry_run:
+ continue
+ if send_lifecycle_snapshot(user.id, snapshot):
+ summary.sent += 1
+ else:
+ summary.errors += 1
+
+
+async def _all_subscriptions_by_customer() -> dict[str, list[StripeSubscriptionFacts]]:
+ page = await stripe_call(stripe.Subscription.list_async, status="all", limit=100)
+ by_customer: dict[str, list[StripeSubscriptionFacts]] = {}
+ async for sub in stripe_list_items(page):
+ facts = StripeSubscriptionFacts.model_validate(sub)
+ if facts.customer:
+ by_customer.setdefault(facts.customer, []).append(facts)
+ return by_customer
+
+
+_USER_BATCH = """
+ SELECT u."id", u."createdAt" AS created_at,
+ u."stripeCustomerId" AS stripe_customer_id,
+ u."subscriptionTier"::text AS subscription_tier
+ FROM {schema_prefix}"User" u
+ WHERE u."id" > $1 AND ($3::boolean OR u."stripeCustomerId" IS NOT NULL
+ OR EXISTS (SELECT 1 FROM {schema_prefix}"SubscriptionTrial" t
+ WHERE t."userId" = u."id"))
+ ORDER BY u."id" LIMIT $2
+"""
+
+
+async def _lifecycle_user_batch(
+ after_id: str, batch_size: int, all_users: bool
+) -> list[LifecycleUser]:
+ return await query_raw_with_schema(
+ _USER_BATCH, after_id, batch_size, all_users, model=LifecycleUser
+ )
+
+
+async def _trials_by_user(user_ids: list[str]) -> dict[str, TrialState | None]:
+ """Trial per user id. None marks a row that exists but can't be read."""
+ rows = await SubscriptionTrial.prisma().find_many(
+ where={"userId": {"in": user_ids}}
+ )
+ trials: dict[str, TrialState | None] = {}
+ for row in rows:
+ try:
+ trials[row.userId] = TrialState.from_db(row)
+ except Exception:
+ trials[row.userId] = None
+ logger.warning(
+ f"Lifecycle sync: unreadable trial row for user {row.userId}",
+ exc_info=True,
+ )
+ return trials
diff --git a/autogpt_platform/backend/backend/data/posthog_lifecycle_sync_integration_test.py b/autogpt_platform/backend/backend/data/posthog_lifecycle_sync_integration_test.py
new file mode 100644
index 0000000000..df48f02ddf
--- /dev/null
+++ b/autogpt_platform/backend/backend/data/posthog_lifecycle_sync_integration_test.py
@@ -0,0 +1,92 @@
+"""Runs the lifecycle sweep's user query against the real database: keyset
+paging over more than one batch, and the billing-history filter."""
+
+import uuid
+
+import pytest
+from prisma.enums import SubscriptionTier
+from prisma.models import SubscriptionTrial, User
+
+from backend.data.posthog_lifecycle import LifecycleUser
+from backend.data.posthog_lifecycle_sync import _lifecycle_user_batch
+from backend.util.json import SafeJson
+
+
+async def lifecycle_users():
+ """Five users whose ids sort after every uuid, so paging starts at them.
+
+ 1 and 4 have a Stripe customer, 3 has only a trial row, 2 and 5 have
+ neither.
+ """
+ prefix = f"zz-lifecycle-{uuid.uuid4()}-"
+ ids = [f"{prefix}{n}" for n in range(1, 6)]
+ customers = {ids[0]: f"cus_{prefix}1", ids[3]: f"cus_{prefix}4"}
+ for user_id in ids:
+ await User.prisma().create(
+ data={
+ "id": user_id,
+ "email": f"{user_id}@example.com",
+ "stripeCustomerId": customers.get(user_id),
+ "subscriptionTier": (
+ SubscriptionTier.PRO
+ if user_id == ids[0]
+ else SubscriptionTier.NO_TIER
+ ),
+ }
+ )
+ await SubscriptionTrial.prisma().create(
+ data={
+ "userId": ids[2],
+ "offer": SafeJson({}),
+ "stripeCustomerId": f"cus_{prefix}3",
+ "checkoutSuccessUrl": "https://example.com/ok",
+ "checkoutCancelUrl": "https://example.com/no",
+ }
+ )
+ yield prefix, ids
+ await User.prisma().delete_many(where={"id": {"in": ids}})
+
+
+async def _page_through(prefix: str, all_users: bool) -> list[list[LifecycleUser]]:
+ batches: list[list[LifecycleUser]] = []
+ after_id = prefix
+ while batch := await _lifecycle_user_batch(after_id, 2, all_users):
+ ours = [user for user in batch if user.id.startswith(prefix)]
+ if ours:
+ batches.append(ours)
+ if len(ours) < len(batch):
+ break
+ after_id = batch[-1].id
+ return batches
+
+
[email protected](loop_scope="session")
+async def test_batches_page_over_users_with_billing_history(lifecycle_users):
+ prefix, ids = lifecycle_users
+
+ batches = await _page_through(prefix, all_users=False)
+
+ assert [[user.id for user in batch] for batch in batches] == [
+ [ids[0], ids[2]],
+ [ids[3]],
+ ]
+ first = batches[0][0]
+ assert first.stripe_customer_id == f"cus_{prefix}1"
+ assert first.subscription_tier == SubscriptionTier.PRO
+ assert first.created_at is not None
+ assert batches[0][1].stripe_customer_id is None
+
+
[email protected](loop_scope="session")
+async def test_all_users_includes_users_without_billing_history(lifecycle_users):
+ prefix, ids = lifecycle_users
+
+ batches = await _page_through(prefix, all_users=True)
+
+ assert [[user.id for user in batch] for batch in batches] == [
+ ids[0:2],
+ ids[2:4],
+ ids[4:5],
+ ]
+ assert batches[0][1].subscription_tier == SubscriptionTier.NO_TIER
diff --git a/autogpt_platform/backend/backend/data/posthog_lifecycle_sync_test.py b/autogpt_platform/backend/backend/data/posthog_lifecycle_sync_test.py
new file mode 100644
index 0000000000..7d97234392
--- /dev/null
+++ b/autogpt_platform/backend/backend/data/posthog_lifecycle_sync_test.py
@@ -0,0 +1,573 @@
+import asyncio
+from datetime import UTC, datetime, timedelta
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+import stripe
+from prisma.enums import SubscriptionTier
+
+from backend.data import posthog_lifecycle_sync as lifecycle
+from backend.data.posthog_lifecycle import LifecycleSnapshot, LifecycleUser
+
+MODULE = "backend.data.posthog_lifecycle_sync"
+SIGNUP = datetime(2026, 1, 1, tzinfo=UTC)
+NOW = datetime(2026, 9, 29, tzinfo=UTC)
+
+
+def stripe_page(*subs: dict, has_more: bool = False) -> stripe.ListObject:
+ return stripe.ListObject.construct_from(
+ {"object": "list", "data": list(subs), "has_more": has_more}, "k"
+ )
+
+
+def stripe_sub(sub_id: str, customer: str, status: str = "active", **extra) -> dict:
+ start = int((NOW - timedelta(days=10)).timestamp())
+ return {
+ "id": sub_id,
+ "customer": customer,
+ "status": status,
+ "start_date": start,
+ "created": start,
+ "metadata": {},
+ **extra,
+ }
+
+
+def db_user(customer: str | None = "cus_1", tier=SubscriptionTier.PRO) -> MagicMock:
+ return MagicMock(
+ id="user-1",
+ createdAt=SIGNUP,
+ stripeCustomerId=customer,
+ subscriptionTier=tier,
+ subscriptionTrial=None,
+ )
+
+
+def posthog():
+ client = MagicMock()
+ with patch(f"{MODULE}.get_posthog_client", return_value=client):
+ yield client
+
+
[email protected](autouse=True)
+def clean_background_state():
+ lifecycle._syncs.clear()
+ yield
+ lifecycle._syncs.clear()
+
+
+# ---- send_lifecycle_snapshot ------------------------------------------------
+
+
+def test_send_sets_and_unsets_on_the_user_id(posthog):
+ snapshot = LifecycleSnapshot(subscription_status="signed", signup_at=SIGNUP)
+
+ assert lifecycle.send_lifecycle_snapshot("user-1", snapshot) is True
+
+ posthog.capture.assert_called_once_with(
+ "$set",
+ distinct_id="user-1",
+ properties={
+ "$set": {
+ "subscription_status": "signed",
+ "signup_at": "2026-01-01T00:00:00+00:00",
+ },
+ "$unset": [
+ "trial_started_at",
+ "subscription_started_at",
+ "subscription_canceled_at",
+ "subscription_ended_at",
+ ],
+ },
+ )
+
+
+def test_send_without_user_id_or_client_is_a_no_op(posthog):
+ snapshot = LifecycleSnapshot(subscription_status="signed")
+ assert lifecycle.send_lifecycle_snapshot("", snapshot) is False
+ posthog.capture.assert_not_called()
+ with patch(f"{MODULE}.get_posthog_client", return_value=None):
+ assert lifecycle.send_lifecycle_snapshot("user-1", snapshot) is False
+
+
+def test_send_swallows_posthog_errors(posthog):
+ posthog.capture.side_effect = RuntimeError("posthog down")
+ snapshot = LifecycleSnapshot(subscription_status="signed")
+ assert lifecycle.send_lifecycle_snapshot("user-1", snapshot) is False
+
+
+# ---- sync_posthog_lifecycle -------------------------------------------------
+
+
+async def test_sync_reads_the_customers_current_subscriptions(posthog):
+ find_unique = AsyncMock(return_value=db_user())
+ list_async = AsyncMock(return_value=stripe_page(stripe_sub("sub_1", "cus_1")))
+ with (
+ patch(f"{MODULE}.User.prisma", return_value=MagicMock(find_unique=find_unique)),
+ patch.object(stripe.Subscription, "list_async", list_async),
+ ):
+ snapshot = await lifecycle.sync_posthog_lifecycle("user-1")
+
+ assert snapshot is not None
+ assert snapshot.subscription_status == "subscribed"
+ list_async.assert_awaited_once_with(customer="cus_1", status="all", limit=100)
+ sent = posthog.capture.call_args.kwargs["properties"]["$set"]
+ assert sent["subscription_status"] == "subscribed"
+ assert sent["signup_at"] == "2026-01-01T00:00:00+00:00"
+
+
+async def test_sync_skips_stripe_for_users_without_a_customer(posthog):
+ find_unique = AsyncMock(return_value=db_user(customer=None, tier=None))
+ list_async = AsyncMock()
+ with (
+ patch(f"{MODULE}.User.prisma", return_value=MagicMock(find_unique=find_unique)),
+ patch.object(stripe.Subscription, "list_async", list_async),
+ ):
+ snapshot = await lifecycle.sync_posthog_lifecycle("user-1")
+
+ assert snapshot is not None
+ assert snapshot.subscription_status == "signed"
+ list_async.assert_not_awaited()
+ posthog.capture.assert_called_once()
+
+
+async def test_sync_uses_a_supplied_subscription_list(posthog):
+ find_unique = AsyncMock(return_value=db_user())
+ list_async = AsyncMock()
+ with (
+ patch(f"{MODULE}.User.prisma", return_value=MagicMock(find_unique=find_unique)),
+ patch.object(stripe.Subscription, "list_async", list_async),
+ ):
+ snapshot = await lifecycle.sync_posthog_lifecycle(
+ "user-1", stripe_subscriptions=[]
+ )
+
+ assert snapshot is not None
+ list_async.assert_not_awaited()
+
+
+async def test_sync_is_a_no_op_when_analytics_is_off():
+ prisma = MagicMock()
+ with (
+ patch(f"{MODULE}.get_posthog_client", return_value=None),
+ patch(f"{MODULE}.User.prisma", prisma),
+ ):
+ assert await lifecycle.sync_posthog_lifecycle("user-1") is None
+ prisma.assert_not_called()
+
+
+async def test_sync_swallows_stripe_errors_and_sends_nothing(posthog):
+ find_unique = AsyncMock(return_value=db_user())
+ with (
+ patch(f"{MODULE}.User.prisma", return_value=MagicMock(find_unique=find_unique)),
+ patch.object(
+ stripe.Subscription,
+ "list_async",
+ AsyncMock(side_effect=stripe.APIConnectionError("down")),
+ ),
+ ):
+ assert await lifecycle.sync_posthog_lifecycle("user-1") is None
+ posthog.capture.assert_not_called()
+
+
+async def test_sync_swallows_posthog_errors(posthog):
+ posthog.capture.side_effect = RuntimeError("posthog down")
+ find_unique = AsyncMock(return_value=db_user(customer=None))
+ with patch(
+ f"{MODULE}.User.prisma", return_value=MagicMock(find_unique=find_unique)
+ ):
+ snapshot = await lifecycle.sync_posthog_lifecycle("user-1")
+ assert snapshot is not None
+
+
+async def test_sync_of_a_deleted_user_sends_nothing(posthog):
+ find_unique = AsyncMock(return_value=None)
+ with patch(
+ f"{MODULE}.User.prisma", return_value=MagicMock(find_unique=find_unique)
+ ):
+ assert await lifecycle.sync_posthog_lifecycle("user-1") is None
+ posthog.capture.assert_not_called()
+
+
+# ---- schedule_posthog_lifecycle_sync ----------------------------------------
+
+
+async def _drain() -> None:
+ # Done tasks leave the set in a callback, so yield to let it run.
+ while lifecycle._background_tasks:
+ await asyncio.gather(*list(lifecycle._background_tasks))
+ await asyncio.sleep(0)
+
+
+async def test_schedule_runs_the_sync_in_the_background(posthog):
+ with patch(f"{MODULE}.sync_posthog_lifecycle", new_callable=AsyncMock) as sync:
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ sync.assert_not_awaited()
+ await _drain()
+ sync.assert_awaited_once_with("user-1")
+
+
+async def test_schedule_coalesces_calls_that_are_still_queued(posthog):
+ with patch(f"{MODULE}.sync_posthog_lifecycle", new_callable=AsyncMock) as sync:
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ await _drain()
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ await _drain()
+ assert sync.await_count == 2
+
+
+async def test_schedule_by_customer_resolves_the_user(posthog):
+ find_first = AsyncMock(return_value=MagicMock(id="user-9"))
+ with (
+ patch(f"{MODULE}.User.prisma", return_value=MagicMock(find_first=find_first)),
+ patch(f"{MODULE}.sync_posthog_lifecycle", new_callable=AsyncMock) as sync,
+ ):
+ lifecycle.schedule_posthog_lifecycle_sync(stripe_customer_id="cus_9")
+ await _drain()
+ find_first.assert_awaited_once_with(where={"stripeCustomerId": "cus_9"})
+ sync.assert_awaited_once_with("user-9")
+
+
+async def test_scheduled_sync_failure_stays_in_the_background(posthog):
+ with patch(
+ f"{MODULE}.sync_posthog_lifecycle",
+ new_callable=AsyncMock,
+ side_effect=RuntimeError("boom"),
+ ):
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ await _drain()
+
+
+async def test_schedule_is_a_no_op_when_analytics_is_off():
+ with (
+ patch(f"{MODULE}.get_posthog_client", return_value=None),
+ patch(f"{MODULE}.sync_posthog_lifecycle", new_callable=AsyncMock) as sync,
+ ):
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ assert not lifecycle._background_tasks
+ sync.assert_not_called()
+
+
+def test_schedule_without_a_running_loop_does_not_raise(posthog):
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ assert not lifecycle._syncs
+
+
+def test_schedule_swallows_client_errors():
+ with patch(f"{MODULE}.get_posthog_client", side_effect=RuntimeError("bad key")):
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+
+
+# ---- sync_all_posthog_lifecycles --------------------------------------------
+
+
+def batch_user(user_id: str, customer: str | None, tier: str = "NO_TIER"):
+ return LifecycleUser(
+ id=user_id,
+ created_at=SIGNUP,
+ stripe_customer_id=customer,
+ subscription_tier=SubscriptionTier(tier),
+ )
+
+
+def sweep_sources():
+ """Two DB batches over three users, and every subscription in Stripe."""
+ batches = [
+ [
+ batch_user("u-sub", "cus_sub", "PRO"),
+ batch_user("u-canceling", "cus_canceling", "PRO"),
+ ],
+ [batch_user("u-ended", "cus_ended")],
+ [],
+ ]
+ subscriptions = stripe_page(
+ stripe_sub("sub_1", "cus_sub"),
+ stripe_sub("sub_2", "cus_canceling", cancel_at_period_end=True),
+ stripe_sub("sub_3", "cus_ended", "canceled", ended_at=1_780_000_000),
+ stripe_sub("sub_4", "cus_not_ours"),
+ )
+ list_async = AsyncMock(return_value=subscriptions)
+ with (
+ patch(
+ f"{MODULE}.query_raw_with_schema",
+ new_callable=AsyncMock,
+ side_effect=batches,
+ ) as query,
+ patch.object(stripe.Subscription, "list_async", list_async),
+ patch(
+ f"{MODULE}.SubscriptionTrial.prisma",
+ return_value=MagicMock(find_many=AsyncMock(return_value=[])),
+ ),
+ ):
+ yield query, list_async
+
+
+async def test_sweep_dry_run_counts_and_sends_nothing(sweep_sources):
+ query, list_async = sweep_sources
+ with patch(f"{MODULE}.get_posthog_client") as get_client:
+ summary = await lifecycle.sync_all_posthog_lifecycles(dry_run=True, now=NOW)
+
+ get_client.assert_not_called()
+ list_async.assert_awaited_once_with(status="all", limit=100)
+ assert summary.aborted is None
+ assert summary.stripe_subscriptions == 4
+ assert summary.users == 3
+ assert summary.sent == 0
+ assert summary.status_counts == {
+ "subscribed": 1,
+ "subscription_canceled": 1,
+ "subscription_ended": 1,
+ }
+ # Default scope: users with billing history only.
+ assert query.await_args_list[0].args[1:] == ("", 500, False)
+ assert query.await_args_list[1].args[1] == "u-canceling"
+
+
+async def test_sweep_sends_every_user_and_flushes_per_batch(sweep_sources, posthog):
+ summary = await lifecycle.sync_all_posthog_lifecycles(now=NOW)
+
+ assert summary.sent == 3
+ assert summary.errors == 0
+ sent = {
+ call.kwargs["distinct_id"]: call.kwargs["properties"]["$set"][
+ "subscription_status"
+ ]
+ for call in posthog.capture.call_args_list
+ }
+ assert sent == {
+ "u-sub": "subscribed",
+ "u-canceling": "subscription_canceled",
+ "u-ended": "subscription_ended",
+ }
+ assert posthog.flush.call_count == 2
+
+
+async def test_sweep_all_users_widens_the_query(sweep_sources, posthog):
+ query, _ = sweep_sources
+ await lifecycle.sync_all_posthog_lifecycles(all_users=True, now=NOW)
+ assert query.await_args_list[0].args[3] is True
+
+
+async def test_sweep_aborts_when_stripe_listing_fails(posthog):
+ with (
+ patch.object(
+ stripe.Subscription,
+ "list_async",
+ AsyncMock(side_effect=stripe.APIConnectionError("down")),
+ ),
+ patch(f"{MODULE}.query_raw_with_schema", new_callable=AsyncMock) as query,
+ ):
+ summary = await lifecycle.sync_all_posthog_lifecycles(now=NOW)
+
+ assert summary.aborted == "Stripe listing failed"
+ query.assert_not_awaited()
+ posthog.capture.assert_not_called()
+
+
+async def test_sweep_aborts_before_stripe_when_posthog_is_off():
+ list_async = AsyncMock()
+ with (
+ patch(f"{MODULE}.get_posthog_client", return_value=None),
+ patch.object(stripe.Subscription, "list_async", list_async),
+ ):
+ summary = await lifecycle.sync_all_posthog_lifecycles(now=NOW)
+ assert summary.aborted == "PostHog is not configured"
+ list_async.assert_not_awaited()
+
+
+async def test_an_aborted_sweep_is_logged(caplog):
+ aborted = lifecycle.LifecycleSyncSummary(
+ dry_run=False, aborted="PostHog is not configured"
+ )
+ with patch(
+ f"{MODULE}.sync_all_posthog_lifecycles", AsyncMock(return_value=aborted)
+ ):
+ await lifecycle._run_sweep()
+ assert "Lifecycle sweep aborted: PostHog is not configured" in caplog.text
+
+
+async def test_sweep_skips_a_user_whose_trial_row_is_unreadable(posthog):
+ broken = MagicMock(userId="u-trial", offer={"not": "an offer"})
+ with (
+ patch(
+ f"{MODULE}.query_raw_with_schema",
+ new_callable=AsyncMock,
+ side_effect=[[batch_user("u-trial", "cus_t")], []],
+ ),
+ patch.object(
+ stripe.Subscription, "list_async", AsyncMock(return_value=stripe_page())
+ ),
+ patch(
+ f"{MODULE}.SubscriptionTrial.prisma",
+ return_value=MagicMock(find_many=AsyncMock(return_value=[broken])),
+ ),
+ ):
+ summary = await lifecycle.sync_all_posthog_lifecycles(now=NOW)
+
+ assert summary.errors == 1
+ assert summary.sent == 0
+ posthog.capture.assert_not_called()
+
+
+# ---- start_posthog_lifecycle_sweep ------------------------------------------
+
+
+async def test_sweep_starter_returns_at_once_and_never_runs_two():
+ release = asyncio.Event()
+
+ async def slow_sweep(**_):
+ await release.wait()
+ return lifecycle.LifecycleSyncSummary(dry_run=False)
+
+ with patch(f"{MODULE}.sync_all_posthog_lifecycles", side_effect=slow_sweep) as run:
+ assert await lifecycle.start_posthog_lifecycle_sweep() is True
+ assert await lifecycle.start_posthog_lifecycle_sweep() is False
+ release.set()
+ await asyncio.gather(*list(lifecycle._sweeps))
+ assert run.await_count == 1
+ assert await lifecycle.start_posthog_lifecycle_sweep() is True
+ await asyncio.gather(*list(lifecycle._sweeps))
+
+
+async def test_sweep_failure_stays_in_the_background():
+ with patch(
+ f"{MODULE}.sync_all_posthog_lifecycles",
+ new_callable=AsyncMock,
+ side_effect=RuntimeError("boom"),
+ ):
+ assert await lifecycle.start_posthog_lifecycle_sweep() is True
+ await asyncio.gather(*list(lifecycle._sweeps))
+
+
+async def test_scheduled_syncs_run_at_most_four_at_a_time(posthog):
+ running = 0
+ peak = 0
+ release = asyncio.Event()
+
+ async def slow_sync(user_id: str):
+ nonlocal running, peak
+ running += 1
+ peak = max(peak, running)
+ await release.wait()
+ running -= 1
+
+ with patch(f"{MODULE}.sync_posthog_lifecycle", side_effect=slow_sync) as sync:
+ for index in range(12):
+ lifecycle.schedule_posthog_lifecycle_sync(f"user-{index}")
+ for _ in range(5):
+ await asyncio.sleep(0)
+ assert peak == lifecycle._MAX_CONCURRENT_SYNCS
+ release.set()
+ await _drain()
+ assert sync.await_count == 12
+ assert peak == lifecycle._MAX_CONCURRENT_SYNCS
+
+
+async def test_a_request_during_a_running_sync_runs_once_more_never_overlapping(
+ posthog,
+):
+ """The race: a sync that started before a write must not be the last
+ one sent, and two syncs for one user must never overlap."""
+ running = 0
+ overlap = False
+ started = asyncio.Event()
+ release = asyncio.Event()
+ reads: list[int] = []
+ state = {"version": 1}
+
+ async def sync(user_id: str):
+ nonlocal running, overlap
+ running += 1
+ overlap = overlap or running > 1
+ reads.append(state["version"])
+ started.set()
+ await release.wait()
+ running -= 1
+
+ with patch(f"{MODULE}.sync_posthog_lifecycle", side_effect=sync) as run:
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ await started.wait()
+ state["version"] = 2
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ release.set()
+ await _drain()
+
+ assert run.await_count == 2
+ assert reads == [1, 2]
+ assert not overlap
+ assert not lifecycle._syncs
+
+
+async def test_customer_hooks_are_coordinated_per_user(posthog):
+ """A customer id is resolved first, then goes through the same per-user
+ queue as a user-id hook, so the two can't overlap for one user."""
+ find_first = AsyncMock(return_value=MagicMock(id="user-1"))
+ with (
+ patch(f"{MODULE}.User.prisma", return_value=MagicMock(find_first=find_first)),
+ patch(f"{MODULE}._schedule_user") as schedule_user,
+ ):
+ lifecycle.schedule_posthog_lifecycle_sync(stripe_customer_id="cus_1")
+ await _drain()
+ schedule_user.assert_called_once_with("user-1")
+
+
+async def test_a_sync_cancelled_while_waiting_for_a_slot_does_not_block_the_user(
+ posthog,
+):
+ release = asyncio.Event()
+ synced: list[str] = []
+
+ async def sync(user_id: str):
+ if user_id.startswith("busy-"):
+ await release.wait()
+ synced.append(user_id)
+
+ with patch(f"{MODULE}.sync_posthog_lifecycle", side_effect=sync):
+ for index in range(lifecycle._MAX_CONCURRENT_SYNCS):
+ lifecycle.schedule_posthog_lifecycle_sync(f"busy-{index}")
+ await asyncio.sleep(0)
+ before = set(lifecycle._background_tasks)
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ (waiting,) = lifecycle._background_tasks - before
+ await asyncio.sleep(0)
+ assert lifecycle._syncs["user-1"] == "queued"
+
+ waiting.cancel()
+ await asyncio.gather(waiting, return_exceptions=True)
+ assert waiting.cancelled()
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ release.set()
+ await _drain()
+
+ assert synced.count("user-1") == 1
+ assert not lifecycle._syncs
+
+
+async def test_a_cancelled_running_sync_keeps_a_requested_rerun(posthog):
+ started = asyncio.Event()
+ calls = 0
+
+ async def sync(user_id: str):
+ nonlocal calls
+ calls += 1
+ if calls == 1:
+ started.set()
+ await asyncio.Event().wait()
+
+ with patch(f"{MODULE}.sync_posthog_lifecycle", side_effect=sync):
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ (running,) = lifecycle._background_tasks
+ await started.wait()
+ lifecycle.schedule_posthog_lifecycle_sync("user-1")
+ assert lifecycle._syncs["user-1"] == "rerun"
+ running.cancel()
+ await asyncio.gather(running, return_exceptions=True)
+ assert running.cancelled()
+ await _drain()
+
+ assert calls == 2
+ assert not lifecycle._syncs
diff --git a/autogpt_platform/backend/backend/data/posthog_lifecycle_test.py b/autogpt_platform/backend/backend/data/posthog_lifecycle_test.py
new file mode 100644
index 0000000000..8d524232e1
--- /dev/null
+++ b/autogpt_platform/backend/backend/data/posthog_lifecycle_test.py
@@ -0,0 +1,588 @@
+from datetime import UTC, datetime, timedelta
+from itertools import permutations
+
+import pytest
+from prisma.enums import SubscriptionTier
+
+from backend.data.posthog_lifecycle import (
+ LifecycleSnapshot,
+ LifecycleUser,
+ StripeSubscriptionFacts,
+ compute_lifecycle_snapshot,
+)
+from backend.data.subscription_trial import TrialState
+from backend.data.subscription_trial_config import AcceptedTrialOffer
+from backend.data.subscription_trial_rejection import TrialRejectionReason
+
+NOW = datetime(2026, 9, 29, 12, 0, tzinfo=UTC)
+SIGNUP = NOW - timedelta(days=90)
+TRIAL_START = NOW - timedelta(days=30)
+
+
+def user(
+ tier: SubscriptionTier = SubscriptionTier.NO_TIER, customer: str | None = "cus_1"
+) -> LifecycleUser:
+ return LifecycleUser(
+ id="user-1",
+ created_at=SIGNUP,
+ stripe_customer_id=customer,
+ subscription_tier=tier,
+ )
+
+
+def trial(**overrides) -> TrialState:
+ """A trial that started 30 days ago and is still running."""
+ values = {
+ "id": "trial-1",
+ "user_id": "user-1",
+ "customer_id": "cus_1",
+ "offer": AcceptedTrialOffer(
+ version="v1",
+ new_users_from=SIGNUP,
+ duration_days=7,
+ tier="PRO",
+ billing_cycle="monthly",
+ daily_cost_limit=1,
+ weekly_cost_limit=1,
+ total_cost_limit=1,
+ onboarding_credit_amount=0,
+ price_id="price_pro",
+ unit_amount=5000,
+ currency="usd",
+ ),
+ "checkout_session_id": "cs_1",
+ "subscription_id": "sub_trial",
+ "checkout_attempt": 0,
+ "success_url": "https://example.com/ok",
+ "cancel_url": "https://example.com/no",
+ "checkout_metadata": {},
+ "status": "trialing",
+ "card_verified_at": TRIAL_START,
+ "started_at": TRIAL_START,
+ "ends_at": NOW + timedelta(days=3),
+ "consumed_at": TRIAL_START,
+ "converted_at": None,
+ "cancel_at_period_end": False,
+ "cost_microdollars": 0,
+ }
+ return TrialState(**{**values, **overrides})
+
+
+def sub(
+ sub_id: str = "sub_paid",
+ status: str = "active",
+ *,
+ start: datetime = NOW - timedelta(days=10),
+ cancel_at_period_end: bool = False,
+ canceled_at: datetime | None = None,
+ ended_at: datetime | None = None,
+ enrollment: str | None = None,
+ trial_end: datetime | None = None,
+) -> StripeSubscriptionFacts:
+ return StripeSubscriptionFacts.model_validate(
+ {
+ "id": sub_id,
+ "customer": "cus_1",
+ "status": status,
+ "cancel_at_period_end": cancel_at_period_end,
+ "start_date": int(start.timestamp()),
+ "created": int(start.timestamp()),
+ "canceled_at": int(canceled_at.timestamp()) if canceled_at else None,
+ "ended_at": int(ended_at.timestamp()) if ended_at else None,
+ "trial_start": int(start.timestamp()) if trial_end else None,
+ "trial_end": int(trial_end.timestamp()) if trial_end else None,
+ "metadata": {"trial_enrollment_id": enrollment} if enrollment else {},
+ }
+ )
+
+
+def snapshot(
+ *,
+ u: LifecycleUser | None = None,
+ t: TrialState | None = None,
+ subs: list[StripeSubscriptionFacts] | None = None,
+) -> LifecycleSnapshot:
+ return compute_lifecycle_snapshot(
+ user=u or user(), trial=t, subscriptions=subs or [], now=NOW
+ )
+
+
+def test_signed_up_only():
+ result = snapshot(u=user(customer=None))
+ assert result == LifecycleSnapshot(subscription_status="signed", signup_at=SIGNUP)
+
+
+def test_customer_without_subscriptions_is_signed():
+ # A Stripe customer is created for credit top-ups too.
+ assert snapshot().subscription_status == "signed"
+
+
+def test_unfinished_trial_checkout_is_signed():
+ result = snapshot(
+ t=trial(status="checkout_pending", consumed_at=None, card_verified_at=None)
+ )
+ assert result.subscription_status == "signed"
+ assert result.trial_started_at is None
+
+
+def test_rejected_trial_is_signed():
+ result = snapshot(
+ t=trial(
+ status="canceled",
+ rejection_reason=TrialRejectionReason.INTRO_OFFER_ALREADY_USED,
+ )
+ )
+ assert result.subscription_status == "signed"
+ assert result.trial_started_at is None
+
+
+def test_in_trial():
+ result = snapshot(
+ t=trial(), subs=[sub("sub_trial", "trialing", enrollment="trial-1")]
+ )
+ assert result == LifecycleSnapshot(
+ subscription_status="in_trial", signup_at=SIGNUP, trial_started_at=TRIAL_START
+ )
+
+
+def test_trial_with_lapsed_card_is_still_in_trial():
+ assert snapshot(t=trial(card_verified_at=None)).subscription_status == "in_trial"
+
+
+def test_trial_set_to_cancel():
+ result = snapshot(t=trial(cancel_at_period_end=True))
+ assert result.subscription_status == "trial_canceled"
+ assert result.trial_started_at == TRIAL_START
+
+
+def test_trial_canceled_immediately():
+ result = snapshot(
+ t=trial(status="canceled", ends_at=NOW - timedelta(days=1)),
+ subs=[sub("sub_trial", "canceled", enrollment="trial-1")],
+ )
+ assert result.subscription_status == "trial_canceled"
+
+
+def test_trial_that_ran_out_on_the_clock():
+ # The webhook for the trial end hasn't landed; the clock alone ends it.
+ result = snapshot(t=trial(ends_at=NOW - timedelta(minutes=1)))
+ assert result.subscription_status == "trial_canceled"
+
+
[email protected]("status", ["past_due", "unpaid"])
+def test_a_failed_first_charge_after_the_trial_is_payment_failed(status: str):
+ # Stripe is still retrying, as with a failed renewal; the backend sends
+ # payment_failed for this state too. It was never paid, so no start date.
+ result = snapshot(
+ t=trial(status=status, ends_at=NOW - timedelta(days=1)),
+ subs=[sub("sub_trial", status, enrollment="trial-1")],
+ )
+ assert result.subscription_status == "payment_failed"
+ assert result.subscription_started_at is None
+
+
+def test_a_trial_canceled_after_its_first_charge_failed_is_trial_canceled():
+ result = snapshot(
+ t=trial(status="canceled", ends_at=NOW - timedelta(days=1)),
+ subs=[sub("sub_trial", "canceled", enrollment="trial-1")],
+ )
+ assert result.subscription_status == "trial_canceled"
+
+
+def test_trial_awaiting_its_first_charge_is_still_in_trial():
+ """Stripe makes the subscription ``active`` at trial end and charges the
+ draft invoice about an hour later; until then it hasn't converted."""
+ t = trial(status="active", ends_at=NOW - timedelta(minutes=10))
+ live = sub("sub_trial", "active", start=TRIAL_START, enrollment="trial-1")
+ result = snapshot(u=user(SubscriptionTier.NO_TIER), t=t, subs=[live])
+ assert result == LifecycleSnapshot(
+ subscription_status="in_trial", signup_at=SIGNUP, trial_started_at=TRIAL_START
+ )
+
+ converted = NOW - timedelta(minutes=1)
+ paid = trial(
+ status="active", ends_at=NOW - timedelta(minutes=10), converted_at=converted
+ )
+ result = snapshot(u=user(SubscriptionTier.PRO), t=paid, subs=[live])
+ assert result.subscription_status == "subscribed"
+ assert result.subscription_started_at == converted
+
+
+def test_converted_trial_starts_its_subscription_at_conversion():
+ converted = NOW - timedelta(days=20)
+ result = snapshot(
+ u=user(SubscriptionTier.PRO),
+ t=trial(status="active", converted_at=converted),
+ subs=[sub("sub_trial", "active", start=TRIAL_START, enrollment="trial-1")],
+ )
+ assert result == LifecycleSnapshot(
+ subscription_status="subscribed",
+ signup_at=SIGNUP,
+ trial_started_at=TRIAL_START,
+ subscription_started_at=converted,
+ )
+
+
+def test_converted_trial_then_canceled_and_ended():
+ converted = NOW - timedelta(days=20)
+ canceled = NOW - timedelta(days=5)
+ ended = NOW - timedelta(days=1)
+ t = trial(status="canceled", converted_at=converted)
+ canceling = sub(
+ "sub_trial",
+ "active",
+ start=TRIAL_START,
+ enrollment="trial-1",
+ cancel_at_period_end=True,
+ canceled_at=canceled,
+ )
+ result = snapshot(t=t, subs=[canceling])
+ assert result.subscription_status == "subscription_canceled"
+ assert result.subscription_canceled_at == canceled
+ assert result.subscription_ended_at is None
+
+ gone = sub(
+ "sub_trial",
+ "canceled",
+ start=TRIAL_START,
+ enrollment="trial-1",
+ canceled_at=canceled,
+ ended_at=ended,
+ )
+ result = snapshot(t=t, subs=[gone])
+ assert result.subscription_status == "subscription_ended"
+ assert result.subscription_started_at == converted
+ assert result.subscription_canceled_at == canceled
+ assert result.subscription_ended_at == ended
+
+
+def test_converted_trial_missing_from_stripe_still_counts_as_ended():
+ converted = NOW - timedelta(days=20)
+ result = snapshot(t=trial(status="canceled", converted_at=converted))
+ assert result.subscription_status == "subscription_ended"
+ assert result.subscription_started_at == converted
+
+
+def test_subscription_from_another_trial_attempt_is_not_paid():
+ stale = sub("sub_old_attempt", "active", enrollment="trial-1")
+ result = snapshot(t=trial(ends_at=NOW - timedelta(days=1)), subs=[stale])
+ assert result.subscription_status == "trial_canceled"
+
+
+def test_subscribed():
+ start = NOW - timedelta(days=10)
+ result = snapshot(u=user(SubscriptionTier.PRO), subs=[sub(start=start)])
+ assert result == LifecycleSnapshot(
+ subscription_status="subscribed",
+ signup_at=SIGNUP,
+ subscription_started_at=start,
+ )
+
+
[email protected]("status", ["past_due", "unpaid"])
+def test_a_failed_renewal_is_payment_failed(status: str):
+ # Lost access (the backend drops them to NO_TIER), but didn't choose to leave.
+ start = NOW - timedelta(days=40)
+ result = snapshot(subs=[sub(status=status, start=start)])
+ assert result == LifecycleSnapshot(
+ subscription_status="payment_failed",
+ signup_at=SIGNUP,
+ subscription_started_at=start,
+ )
+
+
+def test_a_canceled_subscription_after_a_failed_payment_has_ended():
+ # Stripe cancels after its retries run out; the newest state wins.
+ ended = NOW - timedelta(days=1)
+ result = snapshot(subs=[sub(status="canceled", canceled_at=ended, ended_at=ended)])
+ assert result.subscription_status == "subscription_ended"
+
+
+def test_an_active_subscription_wins_over_an_old_past_due_one():
+ result = snapshot(subs=[sub("sub_old", "past_due"), sub("sub_new", "active")])
+ assert result.subscription_status == "subscribed"
+
+
+def test_subscription_set_to_cancel():
+ canceled = NOW - timedelta(days=2)
+ result = snapshot(
+ subs=[sub(cancel_at_period_end=True, canceled_at=canceled)],
+ )
+ assert result.subscription_status == "subscription_canceled"
+ assert result.subscription_canceled_at == canceled
+ assert result.subscription_ended_at is None
+
+
+def test_subscription_ended():
+ canceled = NOW - timedelta(days=5)
+ ended = NOW - timedelta(days=1)
+ result = snapshot(
+ subs=[sub(status="canceled", canceled_at=canceled, ended_at=ended)]
+ )
+ assert result.subscription_status == "subscription_ended"
+ assert result.subscription_canceled_at == canceled
+ assert result.subscription_ended_at == ended
+
+
+def test_never_paid_subscriptions_are_ignored():
+ subs = [sub("a", "incomplete"), sub("b", "incomplete_expired")]
+ assert snapshot(subs=subs).subscription_status == "signed"
+
+
+def test_resubscribe_after_ended_clears_the_old_dates():
+ old = sub(
+ "sub_old",
+ "canceled",
+ start=NOW - timedelta(days=200),
+ canceled_at=NOW - timedelta(days=100),
+ ended_at=NOW - timedelta(days=90),
+ )
+ new_start = NOW - timedelta(days=3)
+ new = sub("sub_new", "active", start=new_start)
+ result = snapshot(u=user(SubscriptionTier.PRO), subs=[old, new])
+ assert result.subscription_status == "subscribed"
+ assert result.subscription_started_at == new_start
+ _, unset = result.person_update()
+ assert "subscription_canceled_at" in unset
+ assert "subscription_ended_at" in unset
+
+
+def test_latest_ended_subscription_supplies_the_dates():
+ first = sub(
+ "sub_1",
+ "canceled",
+ start=NOW - timedelta(days=300),
+ ended_at=NOW - timedelta(days=200),
+ )
+ latest_start = NOW - timedelta(days=100)
+ latest_end = NOW - timedelta(days=10)
+ latest = sub("sub_2", "canceled", start=latest_start, ended_at=latest_end)
+ for order in permutations([first, latest]):
+ result = snapshot(subs=list(order))
+ assert result.subscription_started_at == latest_start
+ assert result.subscription_ended_at == latest_end
+
+
[email protected]("order", list(permutations(range(2))))
+def test_out_of_order_delete_of_old_subscription(order):
+ """A late ``deleted`` for the old sub after ``created`` for the new one.
+
+ The mapping reads every subscription as it is now, so which event came
+ last (and the order Stripe lists them in) can't change the answer.
+ """
+ old = sub(
+ "sub_old",
+ "canceled",
+ start=NOW - timedelta(days=60),
+ canceled_at=NOW - timedelta(days=1),
+ ended_at=NOW - timedelta(days=1),
+ )
+ new = sub("sub_new", "active", start=NOW - timedelta(days=2))
+ subs = [[old, new][i] for i in order]
+ result = snapshot(u=user(SubscriptionTier.PRO), subs=subs)
+ assert result.subscription_status == "subscribed"
+ assert result.subscription_started_at == new.started_at
+ assert result.subscription_canceled_at is None
+
+
+def test_two_live_subscriptions_keep_the_one_not_being_canceled():
+ leaving = sub("sub_a", start=NOW - timedelta(days=1), cancel_at_period_end=True)
+ staying = sub("sub_b", start=NOW - timedelta(days=30))
+ result = snapshot(subs=[leaving, staying])
+ assert result.subscription_status == "subscribed"
+ assert result.subscription_started_at == staying.started_at
+
+
+def test_paid_subscription_wins_over_a_running_trial():
+ result = snapshot(t=trial(), subs=[sub()])
+ assert result.subscription_status == "subscribed"
+ assert result.trial_started_at == TRIAL_START
+
+
[email protected]("customer", [None, "cus_1"])
+def test_enterprise_is_subscribed(customer):
+ ended = sub(status="canceled", ended_at=NOW - timedelta(days=1))
+ result = snapshot(u=user(SubscriptionTier.ENTERPRISE, customer), subs=[ended])
+ assert result == LifecycleSnapshot(
+ subscription_status="subscribed", signup_at=SIGNUP
+ )
+
+
+def test_enterprise_with_a_live_subscription_keeps_its_start():
+ start = NOW - timedelta(days=40)
+ live = sub(start=start, cancel_at_period_end=True)
+ result = snapshot(u=user(SubscriptionTier.ENTERPRISE), subs=[live])
+ assert result == LifecycleSnapshot(
+ subscription_status="subscribed",
+ signup_at=SIGNUP,
+ subscription_started_at=start,
+ )
+
+
+def test_failed_renewal_after_an_upgrade_beats_the_older_canceled_sub():
+ """The old sub is canceled after the new one starts (stale cleanup), so
+ end dates would pick the old one; the newer start wins."""
+ new_start = NOW - timedelta(days=31)
+ old = sub(
+ "old",
+ "canceled",
+ start=NOW - timedelta(days=60),
+ canceled_at=NOW - timedelta(days=30),
+ ended_at=NOW - timedelta(days=30),
+ )
+ new = sub("new", "past_due", start=new_start)
+ for order in permutations([old, new]):
+ result = snapshot(subs=list(order))
+ assert result.subscription_status == "payment_failed"
+ assert result.subscription_started_at == new_start
+ assert result.subscription_ended_at is None
+
+
+def test_a_newer_ended_sub_beats_an_older_failed_one():
+ # A's renewal failed and stayed past_due; the user then took out B, which
+ # ended. B is where they are now.
+ failed = sub("a", "past_due", start=NOW - timedelta(days=90))
+ ended_at = NOW - timedelta(days=2)
+ newer = sub(
+ "b",
+ "canceled",
+ start=NOW - timedelta(days=40),
+ canceled_at=ended_at,
+ ended_at=ended_at,
+ )
+ for order in permutations([failed, newer]):
+ result = snapshot(subs=list(order))
+ assert result.subscription_status == "subscription_ended"
+ assert result.subscription_ended_at == ended_at
+
+
+def test_a_start_date_tie_goes_to_the_sub_that_ended_last():
+ start = NOW - timedelta(days=40)
+ early = sub("a", "canceled", start=start, ended_at=NOW - timedelta(days=20))
+ late_end = NOW - timedelta(days=2)
+ late = sub("b", "canceled", start=start, ended_at=late_end)
+ for order in permutations([early, late]):
+ assert snapshot(subs=list(order)).subscription_ended_at == late_end
+
+
+def test_a_start_date_tie_between_ended_and_failed_is_payment_failed():
+ start = NOW - timedelta(days=40)
+ ended = sub("a", "canceled", start=start, ended_at=NOW - timedelta(days=2))
+ failed = sub("b", "past_due", start=start)
+ for order in permutations([ended, failed]):
+ assert snapshot(subs=list(order)).subscription_status == "payment_failed"
+
+
+def test_a_converted_native_trial_keeps_its_trial_start():
+ start = NOW - timedelta(days=20)
+ converted = sub(
+ "sub_native", "active", start=start, trial_end=start + timedelta(days=7)
+ )
+ result = snapshot(subs=[converted])
+ assert result.subscription_status == "subscribed"
+ assert result.trial_started_at == start
+
+
+def test_stripe_native_trial_is_in_trial():
+ start = NOW - timedelta(days=2)
+ native = sub(
+ "sub_native", "trialing", start=start, trial_end=NOW + timedelta(days=5)
+ )
+ result = snapshot(subs=[native])
+ assert result == LifecycleSnapshot(
+ subscription_status="in_trial", signup_at=SIGNUP, trial_started_at=start
+ )
+
+
+def test_stripe_native_trial_set_to_cancel():
+ native = sub(
+ "sub_native",
+ "trialing",
+ cancel_at_period_end=True,
+ trial_end=NOW + timedelta(days=5),
+ )
+ assert snapshot(subs=[native]).subscription_status == "trial_canceled"
+
+
+def test_stripe_native_trial_past_its_end_is_not_in_trial():
+ native = sub("sub_native", "trialing", trial_end=NOW - timedelta(hours=1))
+ assert snapshot(subs=[native]).subscription_status == "signed"
+
+
+def test_stripe_native_trial_canceled_before_its_first_charge():
+ start = NOW - timedelta(days=10)
+ native = sub(
+ "sub_native",
+ "canceled",
+ start=start,
+ trial_end=NOW - timedelta(days=3),
+ canceled_at=NOW - timedelta(days=5),
+ ended_at=NOW - timedelta(days=5),
+ )
+ result = snapshot(subs=[native])
+ assert result == LifecycleSnapshot(
+ subscription_status="trial_canceled",
+ signup_at=SIGNUP,
+ trial_started_at=start,
+ )
+
+
+def test_stripe_native_trial_that_was_paid_then_canceled_has_ended():
+ ended = NOW - timedelta(days=1)
+ native = sub(
+ "sub_native",
+ "canceled",
+ start=NOW - timedelta(days=40),
+ trial_end=NOW - timedelta(days=26),
+ canceled_at=ended,
+ ended_at=ended,
+ )
+ assert snapshot(subs=[native]).subscription_status == "subscription_ended"
+
+
+def test_our_trial_subscription_is_not_a_native_trial():
+ ours = sub(
+ "sub_trial", "trialing", enrollment="trial-1", trial_end=NOW + timedelta(days=1)
+ )
+ assert snapshot(subs=[ours]).subscription_status == "signed"
+
+
+ "tier",
+ [
+ SubscriptionTier.BASIC,
+ SubscriptionTier.PRO,
+ SubscriptionTier.MAX,
+ SubscriptionTier.BUSINESS,
+ ],
+)
+def test_paid_tier_without_stripe_is_not_a_grant(tier):
+ """The tier column defaulted to PRO for signups from 2026-03-26 to
+ 2026-05-01, so a paid tier with no Stripe customer usually never paid."""
+ assert snapshot(u=user(tier, customer=None)).subscription_status == "signed"
+
+
+def test_stale_paid_tier_with_stripe_customer_follows_stripe():
+ # Stripe owns this tier (the reconcile sweep will downgrade it), so a
+ # missing subscription is not a manual grant.
+ assert snapshot(u=user(SubscriptionTier.PRO)).subscription_status == "signed"
+
+
+def test_person_update_sets_utc_iso_dates_and_unsets_the_rest():
+ local = datetime(2026, 9, 1, 14, 30, tzinfo=UTC) + timedelta(microseconds=5)
+ result = LifecycleSnapshot(
+ subscription_status="in_trial",
+ signup_at=local,
+ trial_started_at=datetime(2026, 9, 2, 8, 0),
+ )
+ to_set, to_unset = result.person_update()
+ assert to_set == {
+ "subscription_status": "in_trial",
+ "signup_at": "2026-09-01T14:30:00+00:00",
+ "trial_started_at": "2026-09-02T08:00:00+00:00",
+ }
+ assert to_unset == [
+ "subscription_started_at",
+ "subscription_canceled_at",
+ "subscription_ended_at",
+ ]
diff --git a/autogpt_platform/backend/backend/data/stripe_reconciliation.py b/autogpt_platform/backend/backend/data/stripe_reconciliation.py
index 2c36a7f5b5..63bee907ed 100644
--- a/autogpt_platform/backend/backend/data/stripe_reconciliation.py
+++ b/autogpt_platform/backend/backend/data/stripe_reconciliation.py
@@ -236,7 +236,9 @@ async def _collect_status_page(
for sub in subs.data:
if (sub.get("metadata") or {}).get("trial_enrollment_id"):
try:
- await sync_subscription_from_stripe(dict(sub))
+ await sync_subscription_from_stripe(
+ dict(sub), track_lifecycle=False
+ )
except (ValueError, stripe.StripeError):
logger.exception(
"Trial reconciliation failed for subscription %s; snapshot is incomplete",
diff --git a/autogpt_platform/backend/backend/data/user.py b/autogpt_platform/backend/backend/data/user.py
index 8137764072..76c37de307 100644
--- a/autogpt_platform/backend/backend/data/user.py
+++ b/autogpt_platform/backend/backend/data/user.py
@@ -34,6 +34,7 @@ from backend.data.model import (
)
from backend.data.notifications import NotificationPreference, NotificationPreferenceDTO
from backend.data.org_migration import ensure_personal_org
+from backend.data.posthog_lifecycle_sync import schedule_posthog_lifecycle_sync
from backend.data.subscription_trial import get_subscription_trial
from backend.util.cache import cached
from backend.util.encryption import JSONCryptor
@@ -110,6 +111,9 @@ async def _get_or_create_user(user_data: dict) -> UserCreationResult:
# race-safe (see ensure_personal_org).
await ensure_personal_org(user.id)
+ if was_created:
+ schedule_posthog_lifecycle_sync(user.id)
+
return UserCreationResult(user=User.from_db(user), was_created=was_created)
except Exception as e:
# Identify by subject only. `user_data` is the decoded JWT (email,
diff --git a/autogpt_platform/backend/backend/executor/scheduler.py b/autogpt_platform/backend/backend/executor/scheduler.py
index 4c80b13ad8..568eda2e89 100644
--- a/autogpt_platform/backend/backend/executor/scheduler.py
+++ b/autogpt_platform/backend/backend/executor/scheduler.py
@@ -940,6 +940,9 @@ def _morning_briefing_crontab(user_id: str) -> str:
return f"{minute} 9 * * *"
+_POSTHOG_LIFECYCLE_JOB_ID = "sync_posthog_lifecycles"
+
+
def _job_timezone_name(job: JobObj) -> str | None:
"""IANA name of a cron job's trigger timezone, if it has one."""
if isinstance(job.trigger, CronTrigger):
@@ -1476,6 +1479,19 @@ def reconcile_stripe_tiers():
run_async(_reconcile(), timeout=STRIPE_RECONCILE_TIMEOUT_SECONDS)
+def sync_posthog_lifecycles():
+ """Resend subscription status and lifecycle dates to PostHog (SECRT-2778).
+
+ Only starts the sweep; it runs inside the database manager.
+ """
+
+ async def _start():
+ db = get_database_manager_async_client()
+ return await db.start_posthog_lifecycle_sweep()
+
+ run_async(_start())
+
+
def execution_accuracy_alerts():
"""Check execution accuracy and send alerts if drops are detected."""
return report_execution_accuracy_alerts()
@@ -2137,6 +2153,10 @@ class Scheduler(AppService):
self.scheduler.add_listener(job_missed_listener, EVENT_JOB_MISSED)
self.scheduler.add_listener(job_max_instances_listener, EVENT_JOB_MAX_INSTANCES)
self.scheduler.start()
+ if self.register_system_tasks:
+ # After start: until then get_job only sees pending jobs, not the
+ # jobstore, so the "leave an unchanged job alone" check can't work.
+ self._register_posthog_lifecycle_sweep()
self._report_parked_jobs()
# Keep the service running since BackgroundScheduler doesn't block
@@ -2784,6 +2804,32 @@ class Scheduler(AppService):
timeout=SCHEDULER_DREAM_OPERATION_TIMEOUT_SECONDS,
)
+ def _register_posthog_lifecycle_sweep(self) -> None:
+ """Daily PostHog lifecycle sweep: the safety net behind the webhook and
+ signup hooks, and what moves a trial that ran out on the clock on.
+
+ Cron rather than an interval, because replace_existing re-arms an
+ interval from every restart. An unchanged job isn't re-registered
+ either: replacing it recomputes ``next_run_time``, so a restart after
+ 04:15 but before the overdue run fires would skip that day's sweep.
+ Left in place, the overdue run fires on start (``coalesce``, no
+ misfire limit).
+ """
+ trigger = CronTrigger.from_crontab("15 4 * * *")
+ existing = self.scheduler.get_job(
+ _POSTHOG_LIFECYCLE_JOB_ID, jobstore=Jobstores.EXECUTION.value
+ )
+ if existing is not None and str(existing.trigger) == str(trigger):
+ return
+ self.scheduler.add_job(
+ sync_posthog_lifecycles,
+ trigger,
+ id=_POSTHOG_LIFECYCLE_JOB_ID,
+ replace_existing=True,
+ max_instances=1,
+ jobstore=Jobstores.EXECUTION.value,
+ )
+
# --- Morning briefing ---
#
# Daily per-user cron at user-local 09:00. The job body's flag gate and
diff --git a/autogpt_platform/backend/backend/executor/scheduler_unit_test.py b/autogpt_platform/backend/backend/executor/scheduler_unit_test.py
index 0999fe25f7..5de7fad9ba 100644
--- a/autogpt_platform/backend/backend/executor/scheduler_unit_test.py
+++ b/autogpt_platform/backend/backend/executor/scheduler_unit_test.py
@@ -48,6 +48,7 @@ from backend.util.exceptions import (
ExpertPrivateTenancyNotFoundError,
UserPaywalledError,
)
+from backend.util.service import EXPOSED_FLAG
from backend.util.settings import Config
_SCHEDULER_PATH = "backend.executor.scheduler"
@@ -2241,3 +2242,40 @@ def test_graph_schedule_rejects_blank_names_before_validation_or_persistence(nam
)
run.assert_not_called()
persist.assert_not_called()
+
+
+class TestPostHogLifecycleSweepRegistration:
+ """An unchanged daily sweep job is left alone, so a restart after 04:15
+ can't push that day's overdue run to tomorrow."""
+
+ def _register(self, existing=None) -> MagicMock:
+ sched = Scheduler.__new__(Scheduler)
+ sched.scheduler = MagicMock()
+ sched.scheduler.get_job.return_value = existing
+ Scheduler._register_posthog_lifecycle_sweep(sched)
+ return sched.scheduler.add_job
+
+ def test_registers_the_daily_cron_when_missing(self):
+ add_job = self._register()
+
+ add_job.assert_called_once()
+ assert add_job.call_args.kwargs["id"] == "sync_posthog_lifecycles"
+ assert "hour='4', minute='15'" in str(add_job.call_args.args[1])
+
+ def test_leaves_an_unchanged_job_alone(self):
+ existing = MagicMock(trigger=CronTrigger.from_crontab("15 4 * * *"))
+
+ self._register(existing=existing).assert_not_called()
+
+ def test_replaces_a_job_whose_schedule_changed(self):
+ existing = MagicMock(trigger=CronTrigger.from_crontab("0 3 * * *"))
+
+ self._register(existing=existing).assert_called_once()
+
+ def test_morning_briefing_stays_an_rpc_endpoint(self):
+ # The sweep registrar sits next to it; the @expose must stay on the
+ # RPC method, not slide onto the private helper.
+ assert getattr(Scheduler.add_morning_briefing_schedule, EXPOSED_FLAG, False)
+ assert not getattr(
+ Scheduler._register_posthog_lifecycle_sweep, EXPOSED_FLAG, False
+ )
diff --git a/autogpt_platform/backend/backend/util/posthog_events.py b/autogpt_platform/backend/backend/util/posthog_events.py
index 1a3afa02c1..be79e396a6 100644
--- a/autogpt_platform/backend/backend/util/posthog_events.py
+++ b/autogpt_platform/backend/backend/util/posthog_events.py
@@ -68,6 +68,10 @@ class PostHogEvent(StrEnum):
SUBSCRIPTION_TRIAL_CONVERTED = "subscription_trial_converted"
SUBSCRIPTION_TRIAL_PAYMENT_FAILED = "subscription_trial_payment_failed"
+ # Person properties: backend/data/posthog_lifecycle_sync.py. PostHog's own
+ # person-update event, not a user action; keep it out of funnels.
+ SET_PERSON_PROPERTIES = "$set"
+
class PlannedPostHogEvent(StrEnum):
"""Planned in the tracking plan and NOT emitted yet (SECRT-2723).
diff --git a/autogpt_platform/backend/backend/util/posthog_events_test.py b/autogpt_platform/backend/backend/util/posthog_events_test.py
index 2af8b97b8e..baa3269ef6 100644
--- a/autogpt_platform/backend/backend/util/posthog_events_test.py
+++ b/autogpt_platform/backend/backend/util/posthog_events_test.py
@@ -45,6 +45,7 @@ LIVE_EVENT_NAMES = {
"subscription_trial_ended",
"subscription_trial_converted",
"subscription_trial_payment_failed",
+ "$set",
}
PLANNED_EVENT_NAMES = {
diff --git a/autogpt_platform/backend/scripts/backfill_posthog_lifecycle.py b/autogpt_platform/backend/scripts/backfill_posthog_lifecycle.py
new file mode 100644
index 0000000000..4fa08b7b70
--- /dev/null
+++ b/autogpt_platform/backend/scripts/backfill_posthog_lifecycle.py
@@ -0,0 +1,110 @@
+"""Backfill subscription status and lifecycle dates onto PostHog persons.
+
+Runs the same sweep as the daily ``sync_posthog_lifecycles`` scheduler job
+(``backend.data.posthog_lifecycle_sync.sync_all_posthog_lifecycles``): one
+Stripe ``Subscription.list(status="all")`` pass mapped to users by customer
+id, trials from the database, and one ``$set`` per user sent in batches.
+
+A dry run (the default) reads Stripe and the database and prints how many
+users land in each status; it sends nothing. ``--send`` sends the ``$set``s.
+By default only users with a Stripe customer or a trial row are covered, as
+in the daily job; ``--all-users`` adds everyone else (``signed``, with
+``signup_at``).
+
+Needs DATABASE_URL and STRIPE_API_KEY, and POSTHOG_API_KEY/POSTHOG_HOST for
+``--send``, pointing at the same environment.
+
+Usage::
+
+ poetry run python scripts/backfill_posthog_lifecycle.py # dry run
+ poetry run python scripts/backfill_posthog_lifecycle.py --send
+ poetry run python scripts/backfill_posthog_lifecycle.py --send --all-users
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+
+
+async def main(send: bool, all_users: bool, batch_size: int) -> int:
+ if not os.environ.get("DATABASE_URL"):
+ raise SystemExit("DATABASE_URL must be set")
+
+ # Imported lazily so --help works without the backend env being loaded.
+ import stripe
+
+ from backend.data.db import connect, disconnect
+ from backend.data.posthog_lifecycle_sync import sync_all_posthog_lifecycles
+ from backend.util.posthog_client import get_posthog_client
+ from backend.util.settings import Settings
+
+ secrets = Settings().secrets
+ if not secrets.stripe_api_key:
+ raise SystemExit("STRIPE_API_KEY must be set")
+ stripe.api_key = secrets.stripe_api_key
+ mode = (
+ "live" if secrets.stripe_api_key.startswith(("sk_live", "rk_live")) else "test"
+ )
+ print(f"Stripe: {mode} mode")
+ if send:
+ if not secrets.posthog_api_key:
+ raise SystemExit("POSTHOG_API_KEY must be set to send")
+ print(f"PostHog: {secrets.posthog_host}")
+
+ await connect()
+ try:
+ summary = await sync_all_posthog_lifecycles(
+ dry_run=not send, all_users=all_users, batch_size=batch_size
+ )
+ finally:
+ await disconnect()
+ client = get_posthog_client()
+ if send and client is not None:
+ client.flush()
+
+ print(format_summary(summary.model_dump()))
+ return 1 if summary.aborted or summary.errors else 0
+
+
+def format_summary(summary: dict) -> str:
+ lines = [
+ "DRY RUN, nothing sent" if summary["dry_run"] else "SENT",
+ f"Stripe subscriptions read: {summary['stripe_subscriptions']}",
+ f"Users mapped: {summary['users']}",
+ ]
+ if summary["aborted"]:
+ lines.append(f"ABORTED: {summary['aborted']}")
+ lines += [f" {status}: {n}" for status, n in summary["status_counts"].items()]
+ if not summary["dry_run"]:
+ lines.append(f"$set sent: {summary['sent']}")
+ lines.append(f"Errors: {summary['errors']}")
+ return "\n".join(lines)
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+ parser = argparse.ArgumentParser(
+ description="Backfill subscription status and lifecycle dates onto PostHog."
+ )
+ parser.add_argument(
+ "--send",
+ action="store_true",
+ help="Send the $set to PostHog. Without it this is a dry run.",
+ )
+ parser.add_argument(
+ "--all-users",
+ action="store_true",
+ help="Include users with no Stripe customer and no trial.",
+ )
+ parser.add_argument("--batch-size", type=int, default=500)
+ args = parser.parse_args(argv)
+ if args.batch_size <= 0:
+ parser.error("--batch-size must be greater than zero")
+ return args
+
+
+if __name__ == "__main__":
+ args = parse_args(sys.argv[1:])
+ sys.exit(asyncio.run(main(args.send, args.all_users, args.batch_size)))
diff --git a/autogpt_platform/backend/scripts/test_backfill_posthog_lifecycle.py b/autogpt_platform/backend/scripts/test_backfill_posthog_lifecycle.py
new file mode 100644
index 0000000000..fe480fdc1c
--- /dev/null
+++ b/autogpt_platform/backend/scripts/test_backfill_posthog_lifecycle.py
@@ -0,0 +1,151 @@
+"""The PostHog lifecycle backfill, end to end against mocked Stripe, database
+and PostHog. Nothing here talks to a real account."""
+
+from datetime import UTC, datetime, timedelta
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+import stripe
+from prisma.enums import SubscriptionTier
+
+import scripts.backfill_posthog_lifecycle as backfill
+from backend.data.posthog_lifecycle import LifecycleUser
+
+SYNC = "backend.data.posthog_lifecycle_sync"
+NOW = datetime.now(UTC)
+
+
+def _sub(sub_id: str, customer: str, status: str, **extra) -> dict:
+ start = int((NOW - timedelta(days=30)).timestamp())
+ return {
+ "id": sub_id,
+ "customer": customer,
+ "status": status,
+ "start_date": start,
+ "metadata": {},
+ **extra,
+ }
+
+
+def _user(user_id: str, customer: str | None, tier: str) -> LifecycleUser:
+ return LifecycleUser(
+ id=user_id,
+ created_at=NOW - timedelta(days=100),
+ stripe_customer_id=customer,
+ subscription_tier=SubscriptionTier(tier),
+ )
+
+
+def secrets():
+ return MagicMock(
+ stripe_api_key="sk_test_unused",
+ posthog_api_key="phc_unused",
+ posthog_host="https://posthog.invalid",
+ )
+
+
+def sources(monkeypatch: pytest.MonkeyPatch, secrets: MagicMock):
+ monkeypatch.setenv("DATABASE_URL", "postgresql://unused")
+ monkeypatch.setattr(stripe, "api_key", stripe.api_key)
+ posthog = MagicMock()
+ subscriptions = stripe.ListObject.construct_from(
+ {
+ "object": "list",
+ "data": [
+ _sub("sub_1", "cus_1", "active"),
+ _sub("sub_2", "cus_2", "canceled", ended_at=int(NOW.timestamp())),
+ ],
+ "has_more": False,
+ },
+ "k",
+ )
+ users = [
+ _user("u-1", "cus_1", "PRO"),
+ _user("u-2", "cus_2", "NO_TIER"),
+ _user("u-3", "cus_3", "NO_TIER"),
+ ]
+ with (
+ patch(
+ "backend.util.settings.Settings", return_value=MagicMock(secrets=secrets)
+ ),
+ patch("backend.data.db.connect", new_callable=AsyncMock),
+ patch("backend.data.db.disconnect", new_callable=AsyncMock),
+ patch.object(
+ stripe.Subscription, "list_async", AsyncMock(return_value=subscriptions)
+ ) as list_async,
+ patch(
+ f"{SYNC}.query_raw_with_schema",
+ new_callable=AsyncMock,
+ side_effect=[users, []],
+ ),
+ patch(
+ f"{SYNC}.SubscriptionTrial.prisma",
+ return_value=MagicMock(find_many=AsyncMock(return_value=[])),
+ ),
+ patch(f"{SYNC}.get_posthog_client", return_value=posthog),
+ patch("backend.util.posthog_client.get_posthog_client", return_value=posthog),
+ ):
+ yield posthog, list_async
+
+
+async def test_dry_run_prints_counts_and_sends_nothing(sources, capsys):
+ posthog, list_async = sources
+
+ assert await backfill.main(send=False, all_users=False, batch_size=500) == 0
+
+ posthog.capture.assert_not_called()
+ list_async.assert_awaited_once_with(status="all", limit=100)
+ out = capsys.readouterr().out
+ assert "DRY RUN, nothing sent" in out
+ assert "Stripe: test mode" in out
+ assert "Users mapped: 3" in out
+ assert " signed: 1" in out
+ assert " subscribed: 1" in out
+ assert " subscription_ended: 1" in out
+ assert "$set sent" not in out
+
+
+async def test_send_mode_sets_every_user_and_flushes(sources, capsys):
+ posthog, _ = sources
+
+ assert await backfill.main(send=True, all_users=False, batch_size=500) == 0
+
+ statuses = {
+ call.kwargs["distinct_id"]: call.kwargs["properties"]["$set"][
+ "subscription_status"
+ ]
+ for call in posthog.capture.call_args_list
+ }
+ assert statuses == {
+ "u-1": "subscribed",
+ "u-2": "subscription_ended",
+ "u-3": "signed",
+ }
+ assert posthog.flush.called
+ assert "$set sent: 3" in capsys.readouterr().out
+
+
+async def test_send_requires_a_posthog_key(sources, secrets):
+ secrets.posthog_api_key = ""
+ with pytest.raises(SystemExit):
+ await backfill.main(send=True, all_users=False, batch_size=500)
+
+
+def test_dry_run_is_the_default():
+ args = backfill.parse_args([])
+ assert args.send is False
+ assert args.all_users is False
+ assert backfill.parse_args(["--send", "--all-users"]).send is True
+
+
[email protected]("size", ["0", "-5"])
+def test_a_non_positive_batch_size_is_rejected(size: str):
+ with pytest.raises(SystemExit) as exit_info:
+ backfill.parse_args(["--batch-size", size])
+ assert exit_info.value.code == 2
+
+
+def test_a_positive_batch_size_is_accepted():
+ assert backfill.parse_args(["--batch-size", "50"]).batch_size == 50
diff --git a/docs/platform/tracking-plan.md b/docs/platform/tracking-plan.md
index dc77422aed..155c252138 100644
--- a/docs/platform/tracking-plan.md
+++ b/docs/platform/tracking-plan.md
@@ -293,6 +293,29 @@ Return visits are `$pageview`; account-level retention is computed in
Arms are also stored in the database (`analytics.experiment_assignment`),
so an experiment can be read in PostHog and Looker alike.
+## Person properties
+
+The backend keeps these on the person (distinct id = platform user id) with
+a `$set` event (`PostHogEvent.SET_PERSON_PROPERTIES`), sent from
+`backend/data/posthog_lifecycle_sync.py` after signup, tier changes and every
+Stripe subscription sync, and by a daily sweep at 04:15 UTC. The lifecycle
+events above mark the moment something happens; these properties hold the
+person's current state, so a cohort or breakdown can filter on them without
+replaying events.
+
+| Property | Value |
+| --- | --- |
+| `subscription_status` | `signed`, `in_trial`, `trial_canceled`, `subscribed`, `subscription_canceled` (set to cancel, active until the period ends), `payment_failed` (a renewal or the first charge after a trial failed; Stripe is retrying), `subscription_ended`. Worked out from the current user, trial and Stripe state, never from the last event received. |
+| `signup_at` | When the user row was created. |
+| `trial_started_at` | When the trial started. |
+| `subscription_started_at` | Start of the current or last paid subscription; for a converted trial, the conversion. |
+| `subscription_canceled_at` | When the subscription was canceled, while `subscription_canceled` or `subscription_ended`. |
+| `subscription_ended_at` | When the subscription ended, while `subscription_ended`. |
+
+Dates are ISO-8601 UTC strings of the lifecycle moment, not of the sync. A
+date that doesn't apply to the current status is `$unset`, never sent as
+null.
+
## Differences from the analytics plan
Left for follow-up changes, so this list and the plan can be compared line by