fix: Recognize devices.types.air_purifier as fan+purifier (H7126) (#37)

The DEVICE_TYPE_PURIFIER constant held the wrong string — "devices.types.purifier"
is not a real Govee API v2.0 value. Four independent primary sources (Govee
Developer API docs, wez/govee2mqtt DeviceType enum, Mavrrick's Hubitat driver,
and two independent H7126 fixtures from disforw/goveelife and CanDuru4/govee)
all confirm the canonical string is "devices.types.air_purifier". The purifier
code path was unreachable until now — no device ever matched the old constant,
so no user ever got a working purifier entity.

Replace the string rather than adding a second alias constant, and expand
is_fan to also match purifiers so H7126-class devices produce a fan entity
with the workMode gearMode speeds (Sleep/Low/High) and Auto preset that the
existing fan platform already handles.

Add test coverage for is_fan, is_purifier, is_light_device, and nested
get_purifier_mode_options() on a mock H7126 shaped after the disforw fixture.
is_purifier had zero test coverage previously — that is how the wrong string
shipped undetected.

Credit: kami587 diagnosed the issue in #37. This commit closes that PR with
a tighter fix that removes the dead string instead of aliasing around it.

See docs/_research/2026-04-08_pr-37-validation.md for full validation.

Author: Tom Lasswell

custom_components/govee/models/device.py

@@ -30,7 +30,7 @@
 DEVICE_TYPE_HEATER = "devices.types.heater"
 DEVICE_TYPE_HUMIDIFIER = "devices.types.humidifier"
 DEVICE_TYPE_FAN = "devices.types.fan"
-DEVICE_TYPE_PURIFIER = "devices.types.purifier"
+DEVICE_TYPE_PURIFIER = "devices.types.air_purifier"
 
 # Instance constants
 INSTANCE_POWER = "powerSwitch"
@@ -290,8 +290,13 @@ def is_plug(self) -> bool:
 
     @property
     def is_fan(self) -> bool:
-        """Check if device is a fan."""
-        return self.device_type == DEVICE_TYPE_FAN
+        """Check if device is a fan or air purifier.
+
+        Air purifiers (devices.types.air_purifier, e.g. H7126) expose the same
+        workMode capability shape as fans — gearMode speeds (Sleep/Low/High)
+        plus an Auto preset — so they map onto the Home Assistant fan entity.
+        """
+        return self.device_type in (DEVICE_TYPE_FAN, DEVICE_TYPE_PURIFIER)
 
     @property
     def is_heater(self) -> bool:

tests/conftest.py

@@ -42,6 +42,7 @@
 DEVICE_TYPE_LIGHT = "devices.types.light"
 DEVICE_TYPE_PLUG = "devices.types.socket"
 DEVICE_TYPE_FAN = "devices.types.fan"
+DEVICE_TYPE_AIR_PURIFIER = "devices.types.air_purifier"
 
 
 @pytest.fixture
@@ -437,6 +438,72 @@ def mock_fan_device(fan_capabilities) -> GoveeDevice:
     )
 
 
+@pytest.fixture
+def air_purifier_capabilities() -> tuple[GoveeCapability, ...]:
+    """Create capabilities for an H7126 air purifier (nested gearMode shape).
+
+    Mirrors the real API response captured in disforw/goveelife's H7126 fixture:
+    workMode options = [gearMode, Custom, Auto]; modeValue.gearMode options =
+    [Sleep, Low, High].
+    """
+    return (
+        GoveeCapability(
+            type=CAPABILITY_ON_OFF,
+            instance=INSTANCE_POWER,
+            parameters={},
+        ),
+        GoveeCapability(
+            type=CAPABILITY_WORK_MODE,
+            instance=INSTANCE_WORK_MODE,
+            parameters={
+                "dataType": "STRUCT",
+                "fields": [
+                    {
+                        "fieldName": "workMode",
+                        "dataType": "ENUM",
+                        "options": [
+                            {"name": "gearMode", "value": 1},
+                            {"name": "Custom", "value": 2},
+                            {"name": "Auto", "value": 3},
+                        ],
+                    },
+                    {
+                        "fieldName": "modeValue",
+                        "dataType": "ENUM",
+                        "options": [
+                            {"name": "gearMode", "options": [
+                                {"name": "Sleep", "value": 1},
+                                {"name": "Low", "value": 2},
+                                {"name": "High", "value": 3},
+                            ]},
+                            {"defaultValue": 0, "name": "Custom"},
+                            {"defaultValue": 0, "name": "Auto"},
+                        ],
+                    },
+                ],
+            },
+        ),
+    )
+
+
+@pytest.fixture
+def mock_air_purifier_device(air_purifier_capabilities) -> GoveeDevice:
+    """Create a mock H7126 air purifier device.
+
+    Uses the canonical ``devices.types.air_purifier`` device type as reported
+    by the real Govee API v2.0 (confirmed against multiple independent fixtures
+    and the official Govee Developer API docs).
+    """
+    return GoveeDevice(
+        device_id="AA:BB:CC:DD:EE:FF:00:66",
+        sku="H7126",
+        name="Bedroom Air Purifier",
+        device_type=DEVICE_TYPE_AIR_PURIFIER,
+        capabilities=air_purifier_capabilities,
+        is_group=False,
+    )
+
+
 @pytest.fixture
 def mock_fan_device_state() -> GoveeDeviceState:
     """Create a mock fan device state."""

tests/test_models.py

@@ -269,6 +269,35 @@ def test_fan_not_light(self, mock_fan_device):
         assert mock_fan_device.is_light_device is False
         assert mock_fan_device.supports_power is True
 
+    def test_air_purifier_is_purifier(self, mock_air_purifier_device):
+        """H7126 (devices.types.air_purifier) must match is_purifier."""
+        assert mock_air_purifier_device.is_purifier is True
+
+    def test_air_purifier_is_fan(self, mock_air_purifier_device):
+        """Air purifiers should also match is_fan so a fan entity gets created.
+
+        Air purifiers expose the same workMode/gearMode capability shape as
+        fans, so they are represented in Home Assistant via the fan platform.
+        """
+        assert mock_air_purifier_device.is_fan is True
+
+    def test_air_purifier_not_light(self, mock_air_purifier_device):
+        """Air purifiers must not be detected as light devices."""
+        assert mock_air_purifier_device.is_light_device is False
+        assert mock_air_purifier_device.is_plug is False
+
+    def test_air_purifier_mode_options(self, mock_air_purifier_device):
+        """get_purifier_mode_options should extract nested gearMode options."""
+        options = mock_air_purifier_device.get_purifier_mode_options()
+        names = [o.get("name") for o in options]
+        assert "Sleep" in names
+        assert "Low" in names
+        assert "High" in names
+
+    def test_fan_is_not_purifier(self, mock_fan_device):
+        """A plain fan (devices.types.fan) must not match is_purifier."""
+        assert mock_fan_device.is_purifier is False
+
     def test_supports_hdmi_source(self, mock_hdmi_device):
         """Test HDMI source support detection."""
         assert mock_hdmi_device.supports_hdmi_source is True