feat(marketplace): user-suggested categories on provider create

Accept category_name as an alternative to category_slug when listing a
service. Names are validated (2–80 chars, at least one letter), deduped
against existing slug/name, and stored with user_suggested=True for admin
review. Serializer rejects both fields at once.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: hc-sousa

src/marketplace/admin.py

@@ -19,8 +19,8 @@ def _reject(modeladmin, request, queryset):
 
 @admin.register(ServiceCategory)
 class ServiceCategoryAdmin(admin.ModelAdmin):
-    list_display = ('name', 'slug', 'island', 'icon')
-    list_filter = ('island',)
+    list_display = ('name', 'slug', 'user_suggested', 'island', 'icon')
+    list_filter = ('island', 'user_suggested')
     search_fields = ('name', 'slug')
     prepopulated_fields = {'slug': ('name',)}
 

src/marketplace/api_v3.py

@@ -91,8 +91,17 @@ def providers_view(request: Request) -> Response:
     session_id = data['session_id'].strip()
     if not session_id:
         return _error('session_required', 'session_id is required', status.HTTP_400_BAD_REQUEST)
-    if not data.get('name') or not data.get('category_slug'):
-        return _error('validation_error', 'name and category_slug are required', status.HTTP_400_BAD_REQUEST)
+    name = (data.get('name') or '').strip()
+    category_slug = (data.get('category_slug') or '').strip()
+    category_name = (data.get('category_name') or '').strip()
+    if not name:
+        return _error('validation_error', 'name is required', status.HTTP_400_BAD_REQUEST)
+    if not category_slug and not category_name:
+        return _error(
+            'validation_error',
+            'category_slug or category_name is required',
+            status.HTTP_400_BAD_REQUEST,
+        )
 
     session_hash = hash_session_id(session_id, request.island.key)
     with for_island(request.island):
@@ -102,6 +111,12 @@ def providers_view(request: Request) -> Response:
             )
         except services.CategoryNotFound:
             return _error('invalid_category', 'Unknown category', status.HTTP_400_BAD_REQUEST)
+        except services.InvalidCategoryName:
+            return _error(
+                'invalid_category_name',
+                'Invalid category name (2–80 characters, at least one letter)',
+                status.HTTP_400_BAD_REQUEST,
+            )
     return Response(payload, status=status.HTTP_201_CREATED)
 
 
@@ -152,6 +167,12 @@ def provider_detail_view(request: Request, provider_id: int) -> Response:
             return _error('not_owner', 'Not allowed', status.HTTP_403_FORBIDDEN)
         except services.CategoryNotFound:
             return _error('invalid_category', 'Unknown category', status.HTTP_400_BAD_REQUEST)
+        except services.InvalidCategoryName:
+            return _error(
+                'invalid_category_name',
+                'Invalid category name (2–80 characters, at least one letter)',
+                status.HTTP_400_BAD_REQUEST,
+            )
     if payload is None:
         return _error('not_found', 'Provider not found', status.HTTP_404_NOT_FOUND)
     return Response(payload)

src/marketplace/migrations/0003_servicecategory_user_suggested.py

@@ -0,0 +1,21 @@
+# Generated by Django 5.0.6 on 2026-06-02 15:37
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("marketplace", "0002_seed_default_categories"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="servicecategory",
+            name="user_suggested",
+            field=models.BooleanField(
+                default=False,
+                help_text="Created by a user when listing a service; review name/slug in admin.",
+            ),
+        ),
+    ]

src/marketplace/models.py

@@ -47,6 +47,10 @@ class ServiceCategory(TenantScopedModel):
     name = models.CharField(max_length=80)
     slug = models.SlugField(max_length=80)
     icon = models.CharField(max_length=64, blank=True, default='')
+    user_suggested = models.BooleanField(
+        default=False,
+        help_text='Created by a user when listing a service; review name/slug in admin.',
+    )
 
     class Meta:
         ordering = ['name']

src/marketplace/serializers.py

@@ -8,7 +8,8 @@
 class ProviderWriteSerializer(serializers.Serializer):
     session_id = serializers.CharField(max_length=128)
     name = serializers.CharField(max_length=160, required=False)
-    category_slug = serializers.SlugField(required=False)
+    category_slug = serializers.SlugField(required=False, allow_blank=True)
+    category_name = serializers.CharField(max_length=80, required=False, allow_blank=True)
     bio = serializers.CharField(required=False, allow_blank=True)
     hourly_rate = serializers.DecimalField(
         max_digits=8, decimal_places=2, required=False, allow_null=True
@@ -19,6 +20,19 @@ class ProviderWriteSerializer(serializers.Serializer):
     latitude = serializers.FloatField(required=False, allow_null=True)
     longitude = serializers.FloatField(required=False, allow_null=True)
 
+    def validate(self, attrs: dict) -> dict:
+        slug = (attrs.get('category_slug') or '').strip()
+        name = (attrs.get('category_name') or '').strip()
+        if slug and name:
+            raise serializers.ValidationError(
+                'Provide category_slug or category_name, not both.'
+            )
+        if slug:
+            attrs['category_slug'] = slug
+        if name:
+            attrs['category_name'] = name
+        return attrs
+
 
 class ReviewWriteSerializer(serializers.Serializer):
     session_id = serializers.CharField(max_length=128)

src/marketplace/services.py

@@ -13,6 +13,7 @@
 from typing import Any
 
 from django.db.models import Avg, Count
+from django.utils.text import slugify
 
 from marketplace.models import Review, ServiceCategory, ServiceProvider
 
@@ -33,6 +34,14 @@ class CategoryNotFound(MarketplaceError):
     """Raised when a write references an unknown category slug."""
 
 
+class InvalidCategoryName(MarketplaceError):
+    """Raised when a suggested category name fails validation."""
+
+
+_CATEGORY_NAME_MIN = 2
+_CATEGORY_NAME_MAX = 80
+
+
 # --------------------------------------------------------------------------- #
 # Serialization
 # --------------------------------------------------------------------------- #
@@ -43,6 +52,7 @@ def serialize_category(category: ServiceCategory) -> dict[str, Any]:
         'name': category.name,
         'slug': category.slug,
         'icon': category.icon,
+        'userSuggested': category.user_suggested,
     }
 
 
@@ -97,6 +107,48 @@ def _resolve_category(slug: str) -> ServiceCategory:
         raise CategoryNotFound(slug) from exc
 
 
+def _normalize_category_name(name: str) -> str:
+    cleaned = ' '.join(name.split())
+    if len(cleaned) < _CATEGORY_NAME_MIN or len(cleaned) > _CATEGORY_NAME_MAX:
+        raise InvalidCategoryName('length')
+    if not any(ch.isalpha() for ch in cleaned):
+        raise InvalidCategoryName('letters')
+    slug = slugify(cleaned)[: _CATEGORY_NAME_MAX]
+    if not slug:
+        raise InvalidCategoryName('slug')
+    return cleaned
+
+
+def get_or_create_category_by_name(*, island, name: str) -> ServiceCategory:
+    """Resolve an existing category or create a user-suggested one."""
+    cleaned = _normalize_category_name(name)
+    slug = slugify(cleaned)[: _CATEGORY_NAME_MAX]
+    existing = ServiceCategory.objects.filter(island=island, slug=slug).first()
+    if existing:
+        return existing
+    existing = ServiceCategory.objects.filter(island=island, name__iexact=cleaned).first()
+    if existing:
+        return existing
+    return ServiceCategory.objects.create(
+        island=island,
+        name=cleaned,
+        slug=slug,
+        user_suggested=True,
+    )
+
+
+def _resolve_category_from_write(*, island, data: dict[str, Any]) -> ServiceCategory:
+    slug = (data.get('category_slug') or '').strip()
+    name = (data.get('category_name') or '').strip()
+    if slug and name:
+        raise InvalidCategoryName('both')
+    if slug:
+        return _resolve_category(slug)
+    if name:
+        return get_or_create_category_by_name(island=island, name=name)
+    raise CategoryNotFound('')
+
+
 # --------------------------------------------------------------------------- #
 # Providers — reads
 # --------------------------------------------------------------------------- #
@@ -180,15 +232,20 @@ def get_provider(
 
 
 def _apply_provider_fields(provider: ServiceProvider, data: dict[str, Any]) -> None:
-    if 'category_slug' in data and data['category_slug']:
-        provider.category = _resolve_category(data['category_slug'])
+    slug = (data.get('category_slug') or '').strip() if 'category_slug' in data else ''
+    name = (data.get('category_name') or '').strip() if 'category_name' in data else ''
+    if slug or name:
+        provider.category = _resolve_category_from_write(
+            island=provider.island,
+            data={'category_slug': slug, 'category_name': name},
+        )
     for field in _PROVIDER_WRITE_FIELDS:
         if field in data:
             setattr(provider, field, data[field])
 
 
 def create_provider(*, island, session_hash: str, data: dict[str, Any]) -> dict[str, Any]:
-    category = _resolve_category(data.get('category_slug', ''))
+    category = _resolve_category_from_write(island=island, data=data)
     provider = ServiceProvider(
         island=island,
         category=category,

src/marketplace/tests/test_api_v3.py

@@ -95,6 +95,49 @@ def test_create_unknown_category(self):
         self.assertEqual(resp.status_code, 400)
         self.assertEqual(resp.json()['error']['code'], 'invalid_category')
 
+    def test_create_with_category_name(self):
+        resp = self.client.post(
+            '/api/v3/marketplace/providers',
+            {
+                'session_id': 'owner',
+                'name': 'Rex Walks',
+                'category_name': 'Dog Walking',
+            },
+            format='json',
+            **SM,
+        )
+        self.assertEqual(resp.status_code, 201)
+        self.assertEqual(resp.json()['category']['slug'], 'dog-walking')
+        cats = self.client.get('/api/v3/marketplace/categories', **SM).json()['categories']
+        slugs = [c['slug'] for c in cats]
+        self.assertIn('dog-walking', slugs)
+        cat = next(c for c in cats if c['slug'] == 'dog-walking')
+        self.assertTrue(cat['userSuggested'])
+
+    def test_create_rejects_both_category_fields(self):
+        resp = self.client.post(
+            '/api/v3/marketplace/providers',
+            {
+                'session_id': 's',
+                'name': 'X',
+                'category_slug': 'electricians',
+                'category_name': 'Other',
+            },
+            format='json',
+            **SM,
+        )
+        self.assertEqual(resp.status_code, 400)
+
+    def test_create_rejects_invalid_category_name(self):
+        resp = self.client.post(
+            '/api/v3/marketplace/providers',
+            {'session_id': 's', 'name': 'X', 'category_name': '!!'},
+            format='json',
+            **SM,
+        )
+        self.assertEqual(resp.status_code, 400)
+        self.assertEqual(resp.json()['error']['code'], 'invalid_category_name')
+
     # --- ownership ----------------------------------------------------------
 
     def test_patch_non_owner_forbidden(self):

src/marketplace/tests/test_services.py

@@ -44,6 +44,44 @@ def test_create_unknown_category_raises(self):
                 data={'category_slug': 'nope', 'name': 'X'},
             )
 
+    def test_create_with_new_category_name(self):
+        result = services.create_provider(
+            island=self.island,
+            session_hash='owner',
+            data={'category_name': 'Dog Walking', 'name': 'Rex Walks'},
+        )
+        cat = ServiceCategory.objects.get(slug='dog-walking')
+        self.assertTrue(cat.user_suggested)
+        self.assertEqual(result['category']['slug'], 'dog-walking')
+
+    def test_create_reuses_existing_category_by_similar_name(self):
+        services.create_provider(
+            island=self.island,
+            session_hash='a',
+            data={'category_name': 'Dog Walking', 'name': 'A'},
+        )
+        before = ServiceCategory.objects.filter(slug='dog-walking').count()
+        services.create_provider(
+            island=self.island,
+            session_hash='b',
+            data={'category_name': 'dog walking', 'name': 'B'},
+        )
+        self.assertEqual(ServiceCategory.objects.filter(slug='dog-walking').count(), before)
+
+    def test_invalid_category_name_rejected(self):
+        with self.assertRaises(services.InvalidCategoryName):
+            services.create_provider(
+                island=self.island,
+                session_hash='x',
+                data={'category_name': '!!', 'name': 'X'},
+            )
+        with self.assertRaises(services.InvalidCategoryName):
+            services.create_provider(
+                island=self.island,
+                session_hash='x',
+                data={'category_slug': 'electricians', 'category_name': 'Other', 'name': 'X'},
+            )
+
     def test_moderate_invalid_action_raises(self):
         result = self._create()
         with self.assertRaises(ValueError):