feat: add a beta firmware update visibility setting

Beta and stable releases were shown identically everywhere (dashboard,
device detail, update dialog), with no way to hide beta-only updates
by default. Adds a "Show beta updates" toggle (off by default) backed
by a new available_firmware_channel field threaded from the scan
gateways (RPC and legacy Gen1) through the API to the frontend, so the
UI can tell which channel an update came from and filter/label it
consistently across the dashboard table, device header, and device
actions card.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VApHaH9KZ6BPV9SwvUAVLH

Author: valentinocossar

packages/api/src/api/controllers/devices.py

@@ -86,6 +86,7 @@ async def scan_devices(
             "device_name": device.device_name,
             "firmware_version": device.firmware_version,
             "available_firmware_version": device.available_firmware_version,
+            "available_firmware_channel": device.available_firmware_channel,
             "response_time": device.response_time,
             "error_message": device.error_message,
             "last_seen": device.last_seen.isoformat() if device.last_seen else None,

packages/api/tests/unit/controllers/test_devices.py

@@ -43,6 +43,7 @@ async def execute(self, scan_request):
                     device_name="Test Device",
                     firmware_version="1.0.0",
                     available_firmware_version="1.2.0",
+                    available_firmware_channel="stable",
                     response_time=0.5,
                     last_seen=datetime.now(),
                 )
@@ -64,6 +65,7 @@ async def execute(self, scan_request):
             assert data[0]["ip"] == "192.168.1.100"
             assert data[0]["status"] == "detected"
             assert data[0]["available_firmware_version"] == "1.2.0"
+            assert data[0]["available_firmware_channel"] == "stable"
             assert data[0]["device_type"] == "SHSW-PM"
             assert data[0]["model_name"] == "Shelly 1PM"
 

packages/core/src/core/domain/entities/discovered_device.py

@@ -25,6 +25,10 @@ class DiscoveredDevice(BaseModel):
     available_firmware_version: str | None = Field(
         None, description="Version an available update would install"
     )
+    available_firmware_channel: str | None = Field(
+        None,
+        description='Channel the available update was found on ("stable" or "beta")',
+    )
     device_name: str | None = Field(None, description="User-defined device name")
     auth_required: bool = Field(
         False, description="Whether device requires authentication"

packages/core/src/core/gateways/device/legacy_device_gateway.py

@@ -157,16 +157,23 @@ async def discover_device(
             )
 
             has_update_flag = self._parse_update_flag(status_data)
-            if has_update_flag is None:
+            update_version = self._parse_update_version(status_data)
+            available_version, available_channel = (
+                update_version if update_version is not None else (None, None)
+            )
+
+            if has_update_flag is None and available_version is None:
                 device_status = Status.DETECTED
                 has_update_value = False
             else:
+                has_update_value = (
+                    bool(has_update_flag) or available_version is not None
+                )
                 device_status = (
                     Status.UPDATE_AVAILABLE
-                    if has_update_flag
+                    if has_update_value
                     else Status.NO_UPDATE_NEEDED
                 )
-                has_update_value = has_update_flag
 
             return DiscoveredDevice(
                 ip=ip,
@@ -175,6 +182,8 @@ async def discover_device(
                 device_type=device_info.get("model") or device_info.get("type"),
                 device_name=device_name,
                 firmware_version=firmware_version,
+                available_firmware_version=available_version,
+                available_firmware_channel=available_channel,
                 response_time=response_time,
                 last_seen=datetime.now(),
                 has_update=has_update_value,
@@ -532,3 +541,36 @@ def _parse_update_flag(self, status_data: dict[str, Any] | None) -> bool | None:
                 return new_version != old_version
 
         return None
+
+    def _parse_update_version(
+        self, status_data: dict[str, Any] | None
+    ) -> tuple[str, str] | None:
+        """Parse the version and channel of an available update, if any.
+
+        Stable takes priority over beta, mirroring the RPC (Gen2+) gateway.
+        Returns ``None`` when no version-bearing update is reported (the
+        boolean-only ``has_update``/``update.has_update`` shorthand some
+        Gen1 firmwares report carries no version and isn't captured here).
+        """
+        if not isinstance(status_data, dict):
+            return None
+
+        update_block = status_data.get("update")
+        if not isinstance(update_block, dict):
+            return None
+
+        new_version = update_block.get("new_version")
+        old_version = update_block.get("old_version")
+        has_stable = bool(update_block.get("has_update")) or (
+            isinstance(new_version, str)
+            and isinstance(old_version, str)
+            and new_version != old_version
+        )
+        if has_stable and isinstance(new_version, str) and new_version:
+            return new_version, "stable"
+
+        beta_version = update_block.get("beta_version")
+        if isinstance(beta_version, str) and beta_version:
+            return beta_version, "beta"
+
+        return None

packages/core/src/core/gateways/device/shelly_device_gateway.py

@@ -107,11 +107,14 @@ async def discover_device(
                 stable_update = update_data.get("stable", {}) if update_data else {}
                 beta_update = update_data.get("beta", {}) if update_data else {}
 
-                available_version = stable_update.get("version") or beta_update.get(
-                    "version"
-                )
+                stable_version = stable_update.get("version")
+                beta_version = beta_update.get("version")
+                available_version = stable_version or beta_version
                 if available_version:
                     device.available_firmware_version = available_version
+                    device.available_firmware_channel = (
+                        "stable" if stable_version else "beta"
+                    )
                     device.status = Status.UPDATE_AVAILABLE
                 else:
                     device.status = Status.NO_UPDATE_NEEDED

packages/core/src/core/use_cases/scan_devices.py

@@ -111,6 +111,7 @@ async def _settle_update_status(self, devices: list[DiscoveredDevice]) -> None:
                 else:
                     device.status = Status.UPDATE_AVAILABLE
                     device.available_firmware_version = release.version
+                    device.available_firmware_channel = "stable"
 
     async def _lookup_release(
         self, firmware_gateway: FirmwareGateway, app_name: str

packages/core/tests/unit/gateways/device/test_legacy_device_gateway.py

@@ -73,6 +73,8 @@ async def test_it_discovers_device_successfully(
         assert device.device_name == "Custom Name"
         assert device.status == Status.NO_UPDATE_NEEDED
         assert device.has_update is False
+        assert device.available_firmware_version is None
+        assert device.available_firmware_channel is None
 
     async def test_it_handles_discovery_failure(self, gateway, mock_http_client):
         mock_http_client.fetch_json.side_effect = Exception("Connection error")
@@ -94,6 +96,75 @@ async def test_it_detects_update_available(
 
         assert device.status == Status.UPDATE_AVAILABLE
         assert device.has_update is True
+        assert device.available_firmware_version is None
+        assert device.available_firmware_channel is None
+
+    async def test_it_captures_the_stable_version_from_the_update_block(
+        self, gateway, mock_http_client, sample_device_info
+    ):
+        mock_http_client.fetch_json.return_value = sample_device_info
+        mock_http_client.fetch_json_optional.side_effect = [
+            {
+                "update": {
+                    "has_update": True,
+                    "new_version": "20240101-000000/v1.14.1-g1234567",
+                    "old_version": "20230913-112003/v1.14.0-gCB16476",
+                }
+            },
+            {},
+        ]
+
+        device = await gateway.discover_device("192.168.1.100")
+
+        assert device.status == Status.UPDATE_AVAILABLE
+        assert device.has_update is True
+        assert device.available_firmware_version == "20240101-000000/v1.14.1-g1234567"
+        assert device.available_firmware_channel == "stable"
+
+    async def test_it_captures_a_beta_only_update_from_the_update_block(
+        self, gateway, mock_http_client, sample_device_info
+    ):
+        mock_http_client.fetch_json.return_value = sample_device_info
+        mock_http_client.fetch_json_optional.side_effect = [
+            {
+                "update": {
+                    "has_update": False,
+                    "beta_version": "20231107-162940/v1.14.1-rc1-g0617c15",
+                }
+            },
+            {},
+        ]
+
+        device = await gateway.discover_device("192.168.1.100")
+
+        assert device.status == Status.UPDATE_AVAILABLE
+        assert device.has_update is True
+        assert (
+            device.available_firmware_version == "20231107-162940/v1.14.1-rc1-g0617c15"
+        )
+        assert device.available_firmware_channel == "beta"
+
+    async def test_it_prefers_stable_over_beta_when_both_are_reported(
+        self, gateway, mock_http_client, sample_device_info
+    ):
+        mock_http_client.fetch_json.return_value = sample_device_info
+        mock_http_client.fetch_json_optional.side_effect = [
+            {
+                "update": {
+                    "has_update": True,
+                    "new_version": "20240101-000000/v1.14.1-g1234567",
+                    "old_version": "20230913-112003/v1.14.0-gCB16476",
+                    "beta_version": "20231107-162940/v1.14.1-rc1-g0617c15",
+                }
+            },
+            {},
+        ]
+
+        device = await gateway.discover_device("192.168.1.100")
+
+        assert device.status == Status.UPDATE_AVAILABLE
+        assert device.available_firmware_version == "20240101-000000/v1.14.1-g1234567"
+        assert device.available_firmware_channel == "stable"
 
     async def test_it_gets_device_status_successfully(
         self,

packages/core/tests/unit/gateways/device/test_shelly_device_gateway.py

@@ -822,6 +822,7 @@ async def test_it_handles_update_info_without_versions(
         assert result is not None
         assert result.status == Status.NO_UPDATE_NEEDED
         assert result.available_firmware_version is None
+        assert result.available_firmware_channel is None
 
     async def test_it_captures_the_available_update_version(
         self, gateway, mock_rpc_client
@@ -842,6 +843,7 @@ async def test_it_captures_the_available_update_version(
         assert result is not None
         assert result.status == Status.UPDATE_AVAILABLE
         assert result.available_firmware_version == "2.6.0"
+        assert result.available_firmware_channel == "stable"
 
     async def test_it_captures_a_beta_only_update_version(
         self, gateway, mock_rpc_client
@@ -859,6 +861,7 @@ async def test_it_captures_a_beta_only_update_version(
         assert result is not None
         assert result.status == Status.UPDATE_AVAILABLE
         assert result.available_firmware_version == "2.7.0-beta1"
+        assert result.available_firmware_channel == "beta"
 
     async def test_it_handles_null_update_info(self, gateway, mock_rpc_client):
         device_info = {"id": "test-device", "model": "SHSW-1", "fw_id": "1.0.0"}

packages/core/tests/unit/use_cases/test_scan_devices.py

@@ -286,6 +286,7 @@ async def test_it_marks_an_update_the_index_publishes(
 
         assert result[0].status == Status.UPDATE_AVAILABLE
         assert result[0].available_firmware_version == "1.8.0"
+        assert result[0].available_firmware_channel == "stable"
         firmware_gateway.get_latest.assert_awaited_once_with("Plus2PM")
 
     async def test_it_marks_a_device_already_on_the_published_build(
@@ -358,6 +359,7 @@ async def test_it_keeps_the_device_reported_available_version(
 
         assert result[0].status == Status.UPDATE_AVAILABLE
         assert result[0].available_firmware_version == "1.9.0"
+        assert result[0].available_firmware_channel is None
         firmware_gateway.get_latest.assert_not_awaited()
 
     async def test_it_skips_a_device_without_an_app_name(

packages/web/src/components/dashboard/device-table.tsx

@@ -82,8 +82,19 @@ export function DeviceTable({ devices, onBulkAction }: DeviceTableProps) {
     initialSettings.tableDensity,
   );
 
+  const getEffectiveStatus = (device: Device): string => {
+    if (
+      !initialSettings.showBetaUpdates &&
+      device.status === "update_available" &&
+      device.available_firmware_channel === "beta"
+    ) {
+      return "no_update_needed";
+    }
+    return device.status;
+  };
+
   const getStatusBadge = (device: Device) => {
-    const statusLower = device.status?.toLowerCase() || "";
+    const statusLower = getEffectiveStatus(device).toLowerCase();
     let variant: "default" | "secondary" | "destructive" | "outline" =
       "default";
 
@@ -104,13 +115,23 @@ export function DeviceTable({ devices, onBulkAction }: DeviceTableProps) {
       variant = "outline";
     }
 
-    return <Badge variant={variant}>{getStatusLabel(device)}</Badge>;
+    return (
+      <div className="flex items-center gap-1.5">
+        <Badge variant={variant}>{getStatusLabel(device)}</Badge>
+        {initialSettings.showBetaUpdates &&
+          device.available_firmware_channel === "beta" && (
+            <Badge className="text-xs px-1.5 py-0 bg-orange-100 text-orange-800 dark:bg-orange-900 dark:text-orange-300">
+              {t("bulkActions.beta")}
+            </Badge>
+          )}
+      </div>
+    );
   };
 
   const getStatusLabel = (device: Device) => {
-    const statusLower = device.status?.toLowerCase() || "";
-    const label = t(`status.${statusLower}`, device.status);
-    return statusLower === "update_available" &&
+    const effectiveStatus = getEffectiveStatus(device).toLowerCase();
+    const label = t(`status.${effectiveStatus}`, device.status);
+    return effectiveStatus === "update_available" &&
       device.available_firmware_version
       ? `${label} (${device.available_firmware_version})`
       : label;