feat: Add Segment events for CheckoutIntent state transitions

Track state changes in CheckoutIntent lifecycle by emitting
appropriate Segment analytics events on transitions

Author: zwidekalanga

enterprise_access/apps/customer_billing/apps.py

@@ -6,3 +6,6 @@
 class CustomerBillingConfig(AppConfig):
     default_auto_field = 'django.db.models.BigAutoField'
     name = 'enterprise_access.apps.customer_billing'
+
+    def ready(self):
+        import enterprise_access.apps.customer_billing.signals  # noqa

enterprise_access/apps/customer_billing/constants.py

@@ -73,6 +73,12 @@ class CheckoutIntentState(StrEnum):
     ERRORED_PROVISIONING = 'errored_provisioning'
     EXPIRED = 'expired'
 
+class CheckoutIntentSegmentEvents:
+    """
+    Segment events for CheckoutIntent lifecycle tracking.
+    """
+    LIFECYCLE_EVENT = 'edx.server.enterprise-access.checkout-intent.lifecycle.event'
+
 
 ALLOWED_CHECKOUT_INTENT_STATE_TRANSITIONS = {
     CheckoutIntentState.CREATED: [

enterprise_access/apps/customer_billing/segment_events.py

@@ -0,0 +1,22 @@
+"""
+Segment event tracking for CheckoutIntent lifecycle events.
+"""
+
+from enterprise_access.apps.api.serializers import CheckoutIntentReadOnlySerializer
+from enterprise_access.apps.customer_billing.constants import (
+    CheckoutIntentSegmentEvents,
+)
+from enterprise_access.apps.track.segment import track_event
+
+
+def track_checkout_intent_event(checkout_intent, previous_state=None, new_state=None):
+    """Track CheckoutIntent lifecycle events (creation and state transitions)."""
+    properties = CheckoutIntentReadOnlySerializer(checkout_intent).data
+    properties["previous_state"] = previous_state
+    properties["new_state"] = new_state or checkout_intent.state
+
+    track_event(
+        lms_user_id=str(checkout_intent.user.id),
+        event_name=CheckoutIntentSegmentEvents.LIFECYCLE_EVENT,
+        properties=properties,
+    )

enterprise_access/apps/customer_billing/signals.py

@@ -0,0 +1,29 @@
+from django.db.models.signals import post_save, pre_save
+from django.dispatch import receiver
+
+from enterprise_access.apps.customer_billing.models import CheckoutIntent
+from enterprise_access.apps.customer_billing.segment_events import (
+    track_checkout_intent_event,
+)
+
+
+@receiver(pre_save, sender=CheckoutIntent)
+def capture_previous_state(sender, instance, **kwargs):
+    """Capture the previous state before saving."""
+    if instance.pk:  # Only for updates, not creation
+        try:
+            instance._previous_state = CheckoutIntent.objects.get(pk=instance.pk).state
+        except CheckoutIntent.DoesNotExist:
+            instance._previous_state = None
+    else:
+        instance._previous_state = None
+
+@receiver(post_save, sender=CheckoutIntent)
+def track_checkout_intent_changes(sender, instance, created, **kwargs):
+    """Automatically track events after save."""
+    if created:
+        # Creation event
+        track_checkout_intent_event(instance, previous_state=None, new_state=instance.state)
+    elif hasattr(instance, '_previous_state') and instance._previous_state != instance.state:
+        # State transition event
+        track_checkout_intent_event(instance, instance._previous_state, instance.state)