Per-site configurable cookie categories (#3)

* feat: per-site configurable cookie categories

Operators can now choose which cookie categories the banner displays
for a given site — useful for sites that genuinely don't use
e.g. marketing cookies and shouldn't be forced to show the toggle.

**Backend**

* New ``enabled_categories`` JSONB column on ``site_configs``,
  ``site_group_configs``, and ``org_configs`` (migration 0003).
  NULL at a level means "inherit"; an explicit list overrides.
* ``config_resolver`` merges ``enabled_categories`` through the
  existing cascade (system → org → group → site) and normalises
  the result via ``_normalise_enabled_categories``:
  - Unknown slugs stripped.
  - ``necessary`` is forced in regardless of the operator's input
    — it's never optional.
  - Empty / invalid values fall back to the full five-category
    default so a cleared field doesn't silently hide the banner.
  - Output is returned in canonical display order so insertion
    order from the cascade doesn't leak into the UI.
* ``build_public_config`` surfaces ``enabled_categories`` to the
  banner-facing public config endpoint.
* Schemas for site/group/org config create + update + response all
  include the new field.

**Banner**

* ``apps/banner/src/banner.ts`` replaces the hard-coded
  ``ALL_CATEGORIES`` / ``NON_ESSENTIAL`` constants with a runtime
  ``resolveEnabledCategories(config)`` helper. ``renderCategories``
  takes the enabled list and only renders toggles for those
  categories; ``nonEssentialFor(enabled)`` derives the user-toggleable
  subset. Falls back to all five when the field is missing in the
  config payload so older banner bundles against newer APIs (and
  vice versa) don't break.
* ``SiteConfig`` type in ``apps/banner/src/types.ts`` has
  ``enabled_categories?: CategorySlug[]`` to match.

**Admin UI**

* New ``SiteCategoriesTab`` component — five checkboxes, ``necessary``
  locked on, with "Reset to inherited" to clear the site override.
  Wired in as a new core tab on ``SiteDetailPage`` between
  Configuration and Cookies.
* ``SiteConfig`` type in ``types/api.ts`` declares ``enabled_categories``
  and a new ``ALL_COOKIE_CATEGORIES`` constant exposing label/description
  metadata shared between the tab component and any future display of
  the list.

**Semantics of a disabled category**

When the operator unticks e.g. ``marketing`` for a site:

* The toggle is not rendered in the banner.
* A visitor can never grant consent for ``marketing``.
* Any cookie or script that classifies into ``marketing`` stays
  blocked permanently by the auto-blocker.

That's the correct behaviour for sites that genuinely don't use a
category: declare it, hide it from the visitor, have the blocker
enforce it.

**Tests**

* ``test_config_resolver.py`` — 13 new cases covering the full
  cascade, ``necessary`` forcing, unknown-slug stripping, empty /
  non-list values, canonical display order, and the public-config
  surface. 37 passed total.
* ``test_SiteCategoriesTab.test.tsx`` — renders all five, locks
  ``necessary``, pre-fills from an override, saves the explicit
  list, and resets to inherited by sending NULL. 6 cases.
* Full API suite (610) and admin-ui suite (139) both green;
  banner bundle builds cleanly with 363 tests passing.

* style: ruff format config_resolver.py

apps/api/alembic/versions/0003_enabled_categories.py

@@ -0,0 +1,46 @@
+"""enabled_categories on site / group / org configs
+
+Revision ID: 0003
+Revises: 0002
+Create Date: 2026-04-14
+
+Per-site control over which cookie categories the banner displays.
+Cascades the same way every other config setting does — site overrides
+site-group overrides org overrides system default (all 5 categories).
+
+Stored as JSONB rather than an array column so the resolver sees a
+plain Python list via SQLAlchemy's JSONB codec and doesn't need
+PostgreSQL-specific array handling in the merge logic.
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = "0003"
+down_revision: str | Sequence[str] | None = "0002"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+_TABLES = ("site_configs", "site_group_configs", "org_configs")
+
+
+def upgrade() -> None:
+    for table in _TABLES:
+        op.add_column(
+            table,
+            sa.Column(
+                "enabled_categories",
+                postgresql.JSONB(astext_type=sa.Text()),
+                nullable=True,
+            ),
+        )
+
+
+def downgrade() -> None:
+    for table in _TABLES:
+        op.drop_column(table, "enabled_categories")

apps/api/src/models/org_config.py

@@ -52,6 +52,11 @@ class OrgConfig(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     privacy_policy_url: Mapped[str | None] = mapped_column(Text, nullable=True)
     terms_url: Mapped[str | None] = mapped_column(Text, nullable=True)
 
+    # Cookie categories shown in the banner. NULL = inherit (system
+    # default is all five). See ``SiteConfig.enabled_categories`` for
+    # the full cascade semantics.
+    enabled_categories: Mapped[list | None] = mapped_column(JSONB, nullable=True)
+
     # Scanning
     scan_schedule_cron: Mapped[str | None] = mapped_column(String(100), nullable=True)
     scan_max_pages: Mapped[int | None] = mapped_column(Integer, nullable=True)

apps/api/src/models/site_config.py

@@ -51,6 +51,13 @@ class SiteConfig(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     privacy_policy_url: Mapped[str | None] = mapped_column(Text, nullable=True)
     terms_url: Mapped[str | None] = mapped_column(Text, nullable=True)
 
+    # Cookie categories shown in the banner. When NULL, inherit from the
+    # cascade (site-group → org → system default of all five). An explicit
+    # list overrides. ``necessary`` is always implicit and will be forced
+    # back into the merged result by the resolver, so operators can't
+    # accidentally drop it.
+    enabled_categories: Mapped[list | None] = mapped_column(JSONB, nullable=True)
+
     # Scanning
     scan_schedule_cron: Mapped[str | None] = mapped_column(String(100), nullable=True)
     scan_max_pages: Mapped[int] = mapped_column(Integer, server_default="50", nullable=False)

apps/api/src/models/site_group_config.py

@@ -52,6 +52,11 @@ class SiteGroupConfig(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     privacy_policy_url: Mapped[str | None] = mapped_column(Text, nullable=True)
     terms_url: Mapped[str | None] = mapped_column(Text, nullable=True)
 
+    # Cookie categories shown in the banner. NULL = inherit (system
+    # default is all five). See ``SiteConfig.enabled_categories`` for
+    # the full cascade semantics.
+    enabled_categories: Mapped[list | None] = mapped_column(JSONB, nullable=True)
+
     # Scanning
     scan_schedule_cron: Mapped[str | None] = mapped_column(String(100), nullable=True)
     scan_max_pages: Mapped[int | None] = mapped_column(Integer, nullable=True)

apps/api/src/schemas/org_config.py

@@ -31,6 +31,7 @@ class OrgConfigUpdate(BaseModel):
     scan_max_pages: int | None = Field(default=None, ge=1, le=1000)
     consent_expiry_days: int | None = Field(default=None, ge=1, le=730)
     consent_retention_days: int | None = Field(default=None, ge=1, le=730)
+    enabled_categories: list[str] | None = None
 
 
 class OrgConfigResponse(BaseModel):
@@ -55,6 +56,7 @@ class OrgConfigResponse(BaseModel):
     scan_max_pages: int | None
     consent_expiry_days: int | None
     consent_retention_days: int | None
+    enabled_categories: list[str] | None = None
     created_at: datetime
     updated_at: datetime
 

apps/api/src/schemas/site.py

@@ -65,6 +65,10 @@ class SiteConfigCreate(BaseModel):
     scan_max_pages: int = Field(default=50, ge=1, le=1000)
     consent_expiry_days: int = Field(default=365, ge=1, le=730)
     consent_retention_days: int | None = Field(default=None, ge=1, le=730)
+    # None = inherit from the cascade (group → org → system). An
+    # explicit list overrides; the resolver re-adds ``necessary``
+    # if omitted and drops any unknown slugs.
+    enabled_categories: list[str] | None = None
 
 
 class SiteConfigUpdate(BaseModel):
@@ -87,6 +91,7 @@ class SiteConfigUpdate(BaseModel):
     scan_max_pages: int | None = Field(default=None, ge=1, le=1000)
     consent_expiry_days: int | None = Field(default=None, ge=1, le=730)
     consent_retention_days: int | None = Field(default=None, ge=1, le=730)
+    enabled_categories: list[str] | None = None
 
 
 class SiteConfigResponse(BaseModel):
@@ -111,6 +116,7 @@ class SiteConfigResponse(BaseModel):
     scan_max_pages: int = 50
     consent_expiry_days: int = 365
     consent_retention_days: int | None = None
+    enabled_categories: list[str] | None = None
     created_at: datetime
     updated_at: datetime
 

apps/api/src/schemas/site_group_config.py

@@ -30,6 +30,7 @@ class SiteGroupConfigUpdate(BaseModel):
     scan_schedule_cron: str | None = None
     scan_max_pages: int | None = Field(default=None, ge=1, le=1000)
     consent_expiry_days: int | None = Field(default=None, ge=1, le=730)
+    enabled_categories: list[str] | None = None
 
 
 class SiteGroupConfigResponse(BaseModel):
@@ -53,6 +54,7 @@ class SiteGroupConfigResponse(BaseModel):
     scan_schedule_cron: str | None
     scan_max_pages: int | None
     consent_expiry_days: int | None
+    enabled_categories: list[str] | None = None
     created_at: datetime
     updated_at: datetime
 

apps/api/src/services/config_resolver.py

@@ -10,6 +10,23 @@ from __future__ import annotations
 
 from typing import Any
 
+# Every known cookie category, in the canonical display order the
+# banner uses. The system default for ``enabled_categories`` is this
+# full list; operators subset from the top via the cascade.
+ALL_CATEGORIES: list[str] = [
+    "necessary",
+    "functional",
+    "analytics",
+    "marketing",
+    "personalisation",
+]
+
+# ``necessary`` is never optional — operators can't hide it and the
+# merged result always contains it, even if it's been accidentally
+# dropped from every layer of the cascade.
+REQUIRED_CATEGORIES: frozenset[str] = frozenset({"necessary"})
+
+
 # System-level defaults (hard-coded, lowest priority)
 SYSTEM_DEFAULTS: dict[str, Any] = {
     "blocking_mode": "opt_in",
@@ -34,6 +51,10 @@ SYSTEM_DEFAULTS: dict[str, Any] = {
     "privacy_policy_url": None,
     "terms_url": None,
     "consent_expiry_days": 365,
+    # All five categories visible by default; any cascade layer may
+    # narrow this to a subset. The resolver normalises the result
+    # via ``_normalise_enabled_categories``.
+    "enabled_categories": ALL_CATEGORIES,
 }
 
 
@@ -77,9 +98,33 @@ def resolve_config(
             if regional_mode:
                 resolved["blocking_mode"] = regional_mode
 
+    resolved["enabled_categories"] = _normalise_enabled_categories(
+        resolved.get("enabled_categories")
+    )
+
     return resolved
 
 
+def _normalise_enabled_categories(value: Any) -> list[str]:
+    """Clean a merged ``enabled_categories`` value into a canonical list.
+
+    - ``None`` / empty / invalid types fall back to the full default.
+    - Unknown slugs are stripped so a typo can't light up a category
+      the banner doesn't actually render.
+    - ``necessary`` is always forced into the output — required
+      categories can never be absent, regardless of what the operator
+      configured. The order mirrors ``ALL_CATEGORIES`` so the banner
+      renders tabs in a consistent order no matter the insertion order.
+    """
+    if not isinstance(value, list) or not value:
+        return list(ALL_CATEGORIES)
+
+    known = set(ALL_CATEGORIES)
+    picked = {slug for slug in value if isinstance(slug, str) and slug in known}
+    picked.update(REQUIRED_CATEGORIES)
+    return [slug for slug in ALL_CATEGORIES if slug in picked]
+
+
 def build_public_config(
     site_id: str,
     resolved: dict[str, Any],
@@ -108,6 +153,9 @@ def build_public_config(
         "consent_expiry_days": resolved["consent_expiry_days"],
         "consent_group_id": resolved.get("consent_group_id"),
         "ab_test": resolved.get("ab_test"),
+        # Public name is ``enabled_categories`` here; the banner schema
+        # converts that to ``enabledCategories`` when it serialises.
+        "enabled_categories": _normalise_enabled_categories(resolved.get("enabled_categories")),
     }
 
 
@@ -128,6 +176,7 @@ CONFIG_FIELDS = (
     "privacy_policy_url",
     "terms_url",
     "consent_expiry_days",
+    "enabled_categories",
 )
 
 

apps/api/tests/test_config_resolver.py

@@ -5,7 +5,9 @@ import uuid
 import pytest
 
 from src.services.config_resolver import (
+    ALL_CATEGORIES,
     SYSTEM_DEFAULTS,
+    _normalise_enabled_categories,
     build_public_config,
     resolve_config,
 )
@@ -256,3 +258,72 @@ class TestConfigRoutes:
         site_id = uuid.uuid4()
         resp = await client.post(f"/api/v1/config/sites/{site_id}/publish")
         assert resp.status_code == 401
+
+
+class TestEnabledCategories:
+    """Cascade semantics for ``enabled_categories``."""
+
+    def test_system_default_is_all_five(self):
+        result = resolve_config({})
+        assert result["enabled_categories"] == ALL_CATEGORIES
+
+    def test_site_override_narrows_system_default(self):
+        result = resolve_config({"enabled_categories": ["necessary", "analytics"]})
+        assert result["enabled_categories"] == ["necessary", "analytics"]
+
+    def test_site_override_beats_org_override(self):
+        result = resolve_config(
+            site_config={"enabled_categories": ["necessary", "marketing"]},
+            org_defaults={"enabled_categories": ["necessary", "analytics"]},
+        )
+        assert result["enabled_categories"] == ["necessary", "marketing"]
+
+    def test_group_override_beats_org_override_when_site_unset(self):
+        result = resolve_config(
+            site_config={},
+            org_defaults={"enabled_categories": ["necessary", "analytics"]},
+            group_defaults={"enabled_categories": ["necessary", "functional"]},
+        )
+        assert result["enabled_categories"] == ["necessary", "functional"]
+
+    def test_unset_site_inherits_org(self):
+        result = resolve_config(
+            site_config={},
+            org_defaults={"enabled_categories": ["necessary", "marketing"]},
+        )
+        assert result["enabled_categories"] == ["necessary", "marketing"]
+
+    def test_necessary_forced_in_when_missing_from_override(self):
+        """Operators can't accidentally drop ``necessary``."""
+        result = resolve_config({"enabled_categories": ["analytics", "marketing"]})
+        assert "necessary" in result["enabled_categories"]
+        assert result["enabled_categories"] == ["necessary", "analytics", "marketing"]
+
+    def test_unknown_slugs_are_stripped(self):
+        result = resolve_config({"enabled_categories": ["necessary", "spam", "analytics"]})
+        assert result["enabled_categories"] == ["necessary", "analytics"]
+
+    def test_empty_list_falls_back_to_default(self):
+        """An empty list is treated as 'no categories configured' → default."""
+        result = resolve_config({"enabled_categories": []})
+        assert result["enabled_categories"] == ALL_CATEGORIES
+
+    def test_non_list_value_falls_back_to_default(self):
+        result = resolve_config({"enabled_categories": "not-a-list"})  # type: ignore[dict-item]
+        assert result["enabled_categories"] == ALL_CATEGORIES
+
+    def test_result_is_in_canonical_display_order(self):
+        """Insertion order from the cascade must not leak into the output."""
+        result = resolve_config({"enabled_categories": ["marketing", "necessary", "analytics"]})
+        assert result["enabled_categories"] == ["necessary", "analytics", "marketing"]
+
+    def test_public_config_includes_enabled_categories(self):
+        resolved = resolve_config({"enabled_categories": ["necessary", "analytics"]})
+        public = build_public_config("site-xyz", resolved)
+        assert public["enabled_categories"] == ["necessary", "analytics"]
+
+    def test_normalise_handles_none(self):
+        assert _normalise_enabled_categories(None) == ALL_CATEGORIES
+
+    def test_normalise_preserves_explicit_full_list(self):
+        assert _normalise_enabled_categories(list(ALL_CATEGORIES)) == ALL_CATEGORIES