Add FeatureFlag enum and feature_flags support to supervisor models (#312)

- Add FeatureFlag StrEnum with SUPERVISOR_V2_API entry and incomplete-list
  docstring (matching SuggestionType pattern)
- Add feature_flags: dict[FeatureFlag | str, bool] to SupervisorInfo for
  non-strict validation (unknown flags fall back to str keys)
- Add feature_flags: dict[FeatureFlag, bool] | None to SupervisorOptions
  for strict validation
- Export FeatureFlag from models __init__
- Update supervisor_info.json fixture with feature_flags field
- Add tests for info parsing, unknown flag fallback, and options serialization

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mdegat01

aiohasupervisor/models/__init__.py

@@ -152,6 +152,7 @@
 )
 from aiohasupervisor.models.supervisor import (
     DetectBlockingIO,
+    FeatureFlag,
     SupervisorInfo,
     SupervisorOptions,
     SupervisorStats,
@@ -203,6 +204,7 @@
     "DiscoveryConfig",
     "DockerNetwork",
     "DownloadBackupOptions",
+    "FeatureFlag",
     "Folder",
     "FreezeOptions",
     "FullBackupOptions",

aiohasupervisor/models/supervisor.py

@@ -18,6 +18,18 @@ class DetectBlockingIO(StrEnum):
     ON_AT_STARTUP = "on_at_startup"
 
 
+class FeatureFlag(StrEnum):
+    """FeatureFlag type.
+
+    This is an incomplete list. Supervisor regularly adds new feature flags as
+    new development features are introduced. Therefore when returning feature flags,
+    some keys may not be in this list and will be parsed as strings on older versions
+    of the client.
+    """
+
+    SUPERVISOR_V2_API = "supervisor_v2_api"
+
+
 # --- OBJECTS ----
 
 
@@ -41,6 +53,7 @@ class SupervisorInfo(ResponseData):
     auto_update: bool
     country: str | None
     detect_blocking_io: bool
+    feature_flags: dict[FeatureFlag | str, bool]
 
 
 @dataclass(frozen=True, slots=True)
@@ -70,3 +83,4 @@ class SupervisorOptions(Options):
     auto_update: bool | None = None
     country: str | None = None
     detect_blocking_io: DetectBlockingIO | None = None
+    feature_flags: dict[FeatureFlag, bool] | None = None

tests/fixtures/supervisor_info.json

@@ -18,6 +18,9 @@
     "country": null,
     "wait_boot": 5,
     "detect_blocking_io": false,
+    "feature_flags": {
+      "supervisor_v2_api": false
+    },
     "addons": [
       {
         "name": "Terminal & SSH",

tests/test_supervisor.py

@@ -1,14 +1,15 @@
 """Test for supervisor management client."""
 
 from ipaddress import IPv4Address
+import json
 
 from aioresponses import aioresponses
 import pytest
 from yarl import URL
 
 from aiohasupervisor import SupervisorClient
 from aiohasupervisor.models import SupervisorOptions, SupervisorUpdateOptions
-from aiohasupervisor.models.supervisor import DetectBlockingIO
+from aiohasupervisor.models.supervisor import DetectBlockingIO, FeatureFlag
 
 from . import load_fixture
 from .const import SUPERVISOR_URL
@@ -45,6 +46,7 @@ async def test_supervisor_info(
     assert info.ip_address == IPv4Address("172.30.32.2")
     assert info.country is None
     assert info.detect_blocking_io is False
+    assert info.feature_flags == {FeatureFlag.SUPERVISOR_V2_API: False}
 
 
 @pytest.mark.parametrize("field", ["version_latest", "arch"])
@@ -54,8 +56,6 @@ async def test_supervisor_info_optional_fields_none(
     field: str,
 ) -> None:
     """Test supervisor info API when optional fields are None."""
-    import json
-
     fixture = json.loads(load_fixture("supervisor_info.json"))
     fixture["data"][field] = None
     responses.get(
@@ -154,6 +154,45 @@ async def test_supervisor_options(
     }
 
 
+async def test_supervisor_info_unknown_feature_flag(
+    responses: aioresponses, supervisor_client: SupervisorClient
+) -> None:
+    """Test supervisor info with an unknown feature flag returns it as a string key."""
+    fixture = json.loads(load_fixture("supervisor_info.json"))
+    fixture["data"]["feature_flags"]["future_feature"] = True
+    responses.get(
+        f"{SUPERVISOR_URL}/supervisor/info",
+        status=200,
+        payload=fixture,
+    )
+    info = await supervisor_client.supervisor.info()
+    assert info.feature_flags[FeatureFlag.SUPERVISOR_V2_API] is False
+    assert info.feature_flags["future_feature"] is True
+
+
+async def test_supervisor_options_feature_flags(
+    responses: aioresponses, supervisor_client: SupervisorClient
+) -> None:
+    """Test supervisor options API with feature_flags."""
+    responses.post(f"{SUPERVISOR_URL}/supervisor/options", status=200)
+    assert (
+        await supervisor_client.supervisor.set_options(
+            SupervisorOptions(
+                feature_flags={FeatureFlag.SUPERVISOR_V2_API: True},
+            )
+        )
+        is None
+    )
+    assert (
+        request := responses.requests[
+            ("POST", URL(f"{SUPERVISOR_URL}/supervisor/options"))
+        ]
+    )
+    assert request[0].kwargs["json"] == {
+        "feature_flags": {"supervisor_v2_api": True},
+    }
+
+
 async def test_supervisor_repair(
     responses: aioresponses, supervisor_client: SupervisorClient
 ) -> None: