feat: change create_intent() to allow blank slug/name

This change is needed to support the use case of creating an intent
WITHOUT an enterprise slug/name, such as during submission of the
PlanDetails page (first page) of the checkout stepper.

ENT-10756

Author: pwnage101

enterprise_access/apps/api/serializers/customer_billing.py

@@ -3,9 +3,26 @@
 """
 from django_countries.serializers import CountryFieldMixin
 from rest_framework import serializers
+from rest_framework.exceptions import APIException
 
 from enterprise_access.apps.customer_billing.constants import ALLOWED_CHECKOUT_INTENT_STATE_TRANSITIONS
-from enterprise_access.apps.customer_billing.models import CheckoutIntent
+from enterprise_access.apps.customer_billing.models import (
+    CheckoutIntent,
+    SlugReservationConflict,
+    TerminalCheckoutIntentConflict
+)
+
+
+class RecordConflictError(APIException):
+    """
+    Raise this to trigger HTTP 422, as an alternative to ValidationError (HTTP 400).
+
+    422 more accurately describes a conflicting database record, whereas 400 means there's an issue
+    with the query structure or values.
+    """
+    status_code = 422
+    default_detail = 'Encountered a conflicting record.'
+    default_code = 'record_conflict_error'
 
 
 # pylint: disable=abstract-method
@@ -176,15 +193,33 @@ def validate_terms_metadata(self, value):
             )
         return value
 
+    def validate(self, attrs):
+        """
+        Perform any cross-field validation.
+        """
+        if attrs.get('enterprise_slug') and not attrs.get('enterprise_name'):
+            raise serializers.ValidationError(
+                {'enterprise_name': 'enterprise_name is required when enterprise_slug is provided.'}
+            )
+        if attrs.get('enterprise_name') and not attrs.get('enterprise_slug'):
+            raise serializers.ValidationError(
+                {'enterprise_slug': 'enterprise_slug is required when enterprise_name is provided.'}
+            )
+        return attrs
+
     def create(self, validated_data):
         """
         Creates a new CheckoutIntent.
         """
-        return CheckoutIntent.create_intent(
-            user=self.context['request'].user,
-            slug=validated_data['enterprise_slug'],
-            name=validated_data['enterprise_name'],
-            quantity=validated_data['quantity'],
-            country=validated_data.get('country'),
-            terms_metadata=validated_data.get('terms_metadata'),
-        )
+        try:
+            return CheckoutIntent.create_intent(
+                user=self.context['request'].user,
+                slug=validated_data['enterprise_slug'],
+                name=validated_data['enterprise_name'],
+                quantity=validated_data['quantity'],
+                country=validated_data.get('country'),
+                terms_metadata=validated_data.get('terms_metadata'),
+            )
+        except (SlugReservationConflict, TerminalCheckoutIntentConflict) as exc:
+            # RecordConflictError is configured to cause a 422 response.
+            raise RecordConflictError() from exc

enterprise_access/apps/api/v1/tests/test_checkout_intent_views.py

@@ -362,43 +362,37 @@ def test_create_or_update_checkout_intent_success(self):
         self.assertEqual(self.checkout_intent_1.terms_metadata, {'version': '2.0', 'updated': True})
 
     @ddt.data(
-        {'quantity': -1},
-        {'quantity': 0},
-        {'quantity': 'invalid'},
-        {'enterprise_slug': ''},
-        {'enterprise_name': ''},
+        # Invalid quantity cases:
+        {'quantity': -1, 'enterprise_slug': 'valid', 'enterprise_name': 'Valid'},
+        {'quantity': 0, 'enterprise_slug': 'valid', 'enterprise_name': 'Valid'},
+        {'quantity': 'invalid', 'enterprise_slug': 'valid', 'enterprise_name': 'Valid'},
+        # Missing slug/name when the other is provided.
+        {'quantity': 10, 'enterprise_slug': '', 'enterprise_name': 'Valid'},
+        {'quantity': 10, 'enterprise_name': 'Valid'},
+        {'quantity': 10, 'enterprise_slug': 'valid', 'enterprise_name': ''},
+        {'quantity': 10, 'enterprise_slug': 'valid'},
     )
     @ddt.unpack
-    def test_create_checkout_intent_invalid_field_values(self, **invalid_field):
+    def test_create_checkout_intent_invalid_field_values(self, **invalid_payload):
         """Test creation fails with invalid field values."""
         other_user = UserFactory()
         self.set_jwt_cookie([{
             'system_wide_role': SYSTEM_ENTERPRISE_LEARNER_ROLE,
             'context': str(uuid.uuid4()),
         }], user=other_user)
 
-        request_data = {
-            'enterprise_slug': 'test-enterprise',
-            'enterprise_name': 'Test Enterprise',
-            'quantity': 10,
-        }
-        request_data.update(invalid_field)
-
         response = self.client.post(
             self.list_url,
-            request_data,
+            invalid_payload,
             format='json'
         )
 
         self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
-        # The field name should be in the error response
-        invalid_field_name = list(invalid_field.keys())[0]
-        self.assertIn(invalid_field_name, response.data)
 
     @ddt.data(
-        {'enterprise_name': 'hello', 'quantity': 10},
-        {'enterprise_slug': 'hello', 'quantity': 10},
-        {'enterprise_name': 'hello', 'enterprise_slug': 'foo'},
+        {},  # Missing quantity.
+        {'enterprise_slug': 'hello', 'quantity': 10},  # Missing enterprise_name.
+        {'enterprise_name': 'Hello', 'quantity': 10},  # Missing enterprise_slug.
     )
     @ddt.unpack
     def test_create_checkout_intent_missing_required_fields(self, **payload):

enterprise_access/apps/customer_billing/api.py

@@ -8,13 +8,18 @@
 
 import stripe
 from django.contrib.auth import get_user_model
+from django.contrib.auth.models import AbstractUser
 from django.core.exceptions import ValidationError
 from django.core.validators import validate_email, validate_slug
 from requests.exceptions import HTTPError
 
 from enterprise_access.apps.api_client.lms_client import LmsApiClient
 from enterprise_access.apps.customer_billing.constants import CHECKOUT_SESSION_ERROR_CODES
-from enterprise_access.apps.customer_billing.models import CheckoutIntent
+from enterprise_access.apps.customer_billing.models import (
+    CheckoutIntent,
+    SlugReservationConflict,
+    TerminalCheckoutIntentConflict
+)
 from enterprise_access.apps.customer_billing.pricing_api import get_ssp_product_pricing
 from enterprise_access.apps.customer_billing.stripe_api import create_subscription_checkout_session
 
@@ -26,7 +31,7 @@ class CheckoutSessionInputValidatorData(TypedDict, total=False):
     """
     `total=False` so that validation does not require all fields to be provided.
     """
-    user: User | None
+    user: AbstractUser | None
     admin_email: str
     full_name: str
     enterprise_slug: str
@@ -38,7 +43,7 @@ class CheckoutSessionInputData(TypedDict, total=True):
     """
     Input parameters for checkout session creation.
     """
-    user: User | None
+    user: AbstractUser | None
     admin_email: str
     enterprise_slug: str
     company_name: str
@@ -402,11 +407,11 @@ def create_free_trial_checkout_session(
     try:
         intent = CheckoutIntent.create_intent(
             user=user,
+            quantity=input_data.get('quantity'),
             slug=input_data.get('enterprise_slug'),
             name=input_data.get('company_name'),
-            quantity=input_data.get('quantity'),
         )
-    except ValidationError as exc:
+    except (SlugReservationConflict, TerminalCheckoutIntentConflict) as exc:
         raise CreateCheckoutSessionValidationError(
             validation_errors_by_field={
                 'enterprise_slug': {

enterprise_access/apps/customer_billing/migrations/0007_checkoutintent_enterprise_name_slug_optional.py

@@ -0,0 +1,35 @@
+# Generated by Django 4.2.24 on 2025-10-02 00:58
+
+import django.core.validators
+from django.db import migrations, models
+import re
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('customer_billing', '0006_customer_uuid_stripe_id'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='checkoutintent',
+            name='enterprise_name',
+            field=models.CharField(blank=True, help_text='Checkout intent enterprise customer name', max_length=255, null=True),
+        ),
+        migrations.AlterField(
+            model_name='checkoutintent',
+            name='enterprise_slug',
+            field=models.SlugField(blank=True, help_text='Checkout intent enterprise customer slug', max_length=255, null=True, validators=[django.core.validators.RegexValidator(re.compile('^[-a-zA-Z0-9_]+\\Z'), 'Enter a valid “slug” consisting of letters, numbers, underscores or hyphens.', 'invalid')]),
+        ),
+        migrations.AlterField(
+            model_name='historicalcheckoutintent',
+            name='enterprise_name',
+            field=models.CharField(blank=True, help_text='Checkout intent enterprise customer name', max_length=255, null=True),
+        ),
+        migrations.AlterField(
+            model_name='historicalcheckoutintent',
+            name='enterprise_slug',
+            field=models.SlugField(blank=True, help_text='Checkout intent enterprise customer slug', max_length=255, null=True, validators=[django.core.validators.RegexValidator(re.compile('^[-a-zA-Z0-9_]+\\Z'), 'Enter a valid “slug” consisting of letters, numbers, underscores or hyphens.', 'invalid')]),
+        ),
+    ]

enterprise_access/apps/customer_billing/models.py

@@ -25,6 +25,14 @@
 User = get_user_model()
 
 
+class TerminalCheckoutIntentConflict(Exception):
+    pass
+
+
+class SlugReservationConflict(Exception):
+    pass
+
+
 class CheckoutIntent(TimeStampedModel):
     """
     Tracks the complete lifecycle of a self-service checkout process:
@@ -101,10 +109,14 @@ class StateChoices(models.TextChoices):
         max_length=255,
     )
     enterprise_name = models.CharField(
+        null=True,
+        blank=True,
         max_length=255,
         help_text="Checkout intent enterprise customer name",
     )
     enterprise_slug = models.SlugField(
+        null=True,
+        blank=True,
         max_length=255,
         validators=[validate_slug],
         help_text="Checkout intent enterprise customer slug"
@@ -386,9 +398,9 @@ def can_reserve(cls, slug=None, name=None, exclude_user=None):
     def create_intent(
         cls,
         user: AbstractUser,
-        slug: str,
-        name: str,
         quantity: int,
+        slug: str | None = None,
+        name: str | None = None,
         country: str | None = None,
         terms_metadata: dict | None = None
     ) -> Self:
@@ -399,22 +411,23 @@ def create_intent(
         not already in use by another checkout flow. If the user already has an intent:
         - If it's in a success state (PAID, FULFILLED), the existing intent is returned unchanged
         - If it's in a failure state (ERRORED_*), a ValueError is raised
-        - If it's in CREATED state, it's updated with the new details
+        - If it's in CREATED state, it's updated with the new details (more like PATCH, not PUT).
 
         The method also cleans up any expired intents first to free up reserved slugs/names.
 
         Args:
             user (User): The Django User who will own this intent
-            slug (str): The enterprise slug to reserve
-            name (str): The enterprise name to reserve
             quantity (int): Number of licenses to create
+            slug (str, Optional): The enterprise slug to reserve
+            name (str, Optional): The enterprise name to reserve
 
         Returns:
             CheckoutIntent: The created or updated intent object
 
         Raises:
-            ValueError: If the slug or name is already reserved by another user
-            ValueError: If the user already has an intent that failed
+            ValueError: If only one of [slug, name] were given, but not the other.
+            SlugReservationConflict: If the slug or name is already reserved by another user
+            TerminalCheckoutIntentConflict: If the user already has an intent that failed
 
         Note:
             This operation is atomic - either the entire reservation succeeds or fails.
@@ -425,28 +438,70 @@ def create_intent(
         with transaction.atomic():
             cls.cleanup_expired()
 
-            if not cls.can_reserve(slug, name, exclude_user=user):
-                raise ValueError(f"Slug '{slug}' or name '{name}' is already reserved")
+            if bool(slug) != bool(name):
+                raise ValueError("slug and name must either both be given or neither be given.")
 
             existing_intent = cls.objects.filter(user=user).first()
 
-            expires_at = timezone.now() + timedelta(minutes=cls.get_reservation_duration())
-
+            # If an existing intent has already reached a terminal state, exit fast.
             if existing_intent:
                 if existing_intent.state in cls.SUCCESS_STATES:
                     return existing_intent
 
                 if existing_intent.state in cls.FAILURE_STATES:
-                    raise ValueError("Failed checkout record already exists")
+                    raise TerminalCheckoutIntentConflict("Failed checkout record already exists")
+
+            # Establish whether or not a new slug needs to be reserved. This logic is really only an
+            # optimization to avoid unnecessary DB lookups to search for reservation conflicts (via
+            # can_reserve()) in cases where we know the reservation is not changing.
+            #
+            #       |    Slug    |  Intent  |      A Slug       | Requested Slug |    Requested Slug
+            #  Case | Requested? | Existed? | Already Reserved? | Is Different?  | Needs To Be Reserved
+            # ------+------------+----------+-------------------+----------------+---------------------
+            #   1   |     no     |    no    |        N/A        |      N/A       |        no
+            #   2   |     no     |    yes   |        no         |      N/A       |        no
+            #   3   |     no     |    yes   |        yes        |      N/A       |        no
+            #   4   |     yes    |    no    |        N/A        |      N/A       |        yes
+            #   5   |     yes    |    yes   |        no         |      N/A       |        yes
+            #   6   |     yes    |    yes   |        yes        |      no        |        no
+            #   7   |     yes    |    yes   |        yes        |      yes       |        yes
+            if slug:
+                if existing_intent:
+                    slug_changing = slug != existing_intent.enterprise_slug
+                    name_changing = name != existing_intent.enterprise_name
+                    should_reserve_new_slug = slug_changing or name_changing  # Cases 5, 6, 7
+                else:
+                    should_reserve_new_slug = True  # Case 4
+            else:
+                should_reserve_new_slug = False  # Cases 1, 2, 3
+
+            # If we are reserving a new slug, then gate this whole view on it not already being reserved.
+            if should_reserve_new_slug:
+                if not cls.can_reserve(slug, name, exclude_user=user):
+                    raise SlugReservationConflict(f"Slug '{slug}' or name '{name}' is already reserved")
+
+            expires_at = timezone.now() + timedelta(minutes=cls.get_reservation_duration())
+
+            # The remaining code essentially performs an update_or_create(), but we're not
+            # using update_or_create() because we already have the existing intent and
+            # don't need to spend a DB query looking it up again. Also, wouldn't be able
+            # to do the terms_metadata merging logic which could come in handy in case
+            # this ever gets called multiple times and we have terms on multiple pages.
 
-                # Update the existing CREATED or EXPIRED intent
+            if existing_intent:
+                # Found an existing CREATED or EXPIRED intent, so update it.
+
+                # Force update certain fields.
                 existing_intent.state = CheckoutIntentState.CREATED
-                existing_intent.enterprise_slug = slug
-                existing_intent.enterprise_name = name
                 existing_intent.quantity = quantity
                 existing_intent.expires_at = expires_at
-                existing_intent.country = country
-                existing_intent.terms_metadata = terms_metadata
+
+                # Any of the following could be None since they're optional, so lets only update them if supplied.
+                existing_intent.enterprise_slug = slug or existing_intent.enterprise_slug
+                existing_intent.enterprise_name = name or existing_intent.enterprise_name
+                existing_intent.country = country or existing_intent.country
+                existing_intent.terms_metadata = (existing_intent.terms_metadata or {}) | (terms_metadata or {})
+
                 existing_intent.save()
                 return existing_intent