Add HEOS options flow for optional authentication

homeassistant/components/heos/__init__.py

@@ -7,10 +7,23 @@
 from datetime import timedelta
 import logging
 
-from pyheos import Heos, HeosError, HeosOptions, HeosPlayer, const as heos_const
+from pyheos import (
+    Credentials,
+    Heos,
+    HeosError,
+    HeosOptions,
+    HeosPlayer,
+    const as heos_const,
+)
 
 from homeassistant.config_entries import ConfigEntry
-from homeassistant.const import CONF_HOST, EVENT_HOMEASSISTANT_STOP, Platform
+from homeassistant.const import (
+    CONF_HOST,
+    CONF_PASSWORD,
+    CONF_USERNAME,
+    EVENT_HOMEASSISTANT_STOP,
+    Platform,
+)
 from homeassistant.core import CALLBACK_TYPE, HomeAssistant, callback
 from homeassistant.exceptions import ConfigEntryNotReady, HomeAssistantError
 from homeassistant.helpers import device_registry as dr, entity_registry as er
@@ -56,9 +69,22 @@ async def async_setup_entry(hass: HomeAssistant, entry: HeosConfigEntry) -> bool
         hass.config_entries.async_update_entry(entry, unique_id=DOMAIN)
 
     host = entry.data[CONF_HOST]
+    credentials: Credentials | None = None
+    if entry.options:
+        credentials = Credentials(
+            entry.options[CONF_USERNAME], entry.options[CONF_PASSWORD]
+        )
+
     # Setting all_progress_events=False ensures that we only receive a
     # media position update upon start of playback or when media changes
-    controller = Heos(HeosOptions(host, all_progress_events=False, auto_reconnect=True))
+    controller = Heos(
+        HeosOptions(
+            host,
+            all_progress_events=False,
+            auto_reconnect=True,
+            credentials=credentials,
+        )
+    )
     try:
         await controller.connect()
     # Auto reconnect only operates if initial connection was successful.
@@ -82,13 +108,8 @@ async def disconnect_controller(event):
         if controller.is_signed_in:
             favorites = await controller.get_favorites()
         else:
-            _LOGGER.warning(
-                (
-                    "%s is not logged in to a HEOS account and will be unable to"
-                    " retrieve HEOS favorites: Use the 'heos.sign_in' service to"
-                    " sign-in to a HEOS account"
-                ),
-                host,
+            _LOGGER.info(
+                "The HEOS System is not logged in: Enter credentials in the integration options to access favorites and streaming services"
             )
         inputs = await controller.get_input_sources()
     except HeosError as error:

homeassistant/components/heos/config_flow.py

@@ -1,17 +1,27 @@
 """Config flow to configure Heos."""
 
-from typing import TYPE_CHECKING, Any
+import logging
+from typing import TYPE_CHECKING, Any, cast
 from urllib.parse import urlparse
 
-from pyheos import Heos, HeosError, HeosOptions
+from pyheos import CommandFailedError, Heos, HeosError, HeosOptions
 import voluptuous as vol
 
 from homeassistant.components import ssdp
-from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
-from homeassistant.const import CONF_HOST
+from homeassistant.config_entries import (
+    ConfigEntry,
+    ConfigFlow,
+    ConfigFlowResult,
+    OptionsFlow,
+)
+from homeassistant.const import CONF_HOST, CONF_PASSWORD, CONF_USERNAME
+from homeassistant.core import callback
+from homeassistant.helpers import selector
 
 from .const import DOMAIN
 
+_LOGGER = logging.getLogger(__name__)
+
 
 def format_title(host: str) -> str:
     """Format the title for config entries."""
@@ -36,6 +46,12 @@ class HeosFlowHandler(ConfigFlow, domain=DOMAIN):
 
     VERSION = 1
 
+    @staticmethod
+    @callback
+    def async_get_options_flow(config_entry: ConfigEntry) -> OptionsFlow:
+        """Create the options flow."""
+        return HeosOptionsFlowHandler()
+
     async def async_step_ssdp(
         self, discovery_info: ssdp.SsdpServiceInfo
     ) -> ConfigFlowResult:
@@ -100,3 +116,72 @@ async def async_step_reconfigure(
             data_schema=vol.Schema({vol.Required(CONF_HOST, default=host): str}),
             errors=errors,
         )
+
+
+OPTIONS_SCHEMA = vol.Schema(
+    {
+        vol.Optional(CONF_USERNAME): selector.TextSelector(),
+        vol.Optional(CONF_PASSWORD): selector.TextSelector(
+            selector.TextSelectorConfig(type=selector.TextSelectorType.PASSWORD)
+        ),
+    }
+)
+
+
+class HeosOptionsFlowHandler(OptionsFlow):
+    """Define HEOS options flow."""
+
+    async def async_step_init(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Manage the options."""
+        errors: dict[str, str] = {}
+        if user_input is not None:
+            authentication = CONF_USERNAME in user_input or CONF_PASSWORD in user_input
+            if authentication and CONF_USERNAME not in user_input:
+                errors[CONF_USERNAME] = "username_missing"
+            if authentication and CONF_PASSWORD not in user_input:
+                errors[CONF_PASSWORD] = "password_missing"
+
+            if not errors:
+                heos = cast(
+                    Heos, self.config_entry.runtime_data.controller_manager.controller
+                )
+
+                try:
+                    if user_input:
+                        # Attempt to login
+                        try:
+                            await heos.sign_in(
+                                user_input[CONF_USERNAME], user_input[CONF_PASSWORD]
+                            )
+                            _LOGGER.info(
+                                "Successfully signed-in to HEOS Account: %s",
+                                heos.signed_in_username,
+                            )
+                        except CommandFailedError as err:
+                            if err.error_id in (6, 8, 10):  # Auth-specific errors
+                                errors["base"] = "invalid_auth"
+                                _LOGGER.info(
+                                    "Failed to sign-in to HEOS Account: %s", err
+                                )
+                            else:
+                                raise  # Re-raise unexpected error
+                    else:
+                        # Log out
+                        await heos.sign_out()
+                        _LOGGER.info("Successfully signed-out of HEOS Account")
+                except HeosError:
+                    errors["base"] = "unknown"
+                    _LOGGER.exception("Unexpected error occurred during sign-in/out")
+
+            if not errors:
+                return self.async_create_entry(data=user_input)
+
+        return self.async_show_form(
+            errors=errors,
+            step_id="init",
+            data_schema=self.add_suggested_values_to_schema(
+                OPTIONS_SCHEMA, user_input or self.config_entry.options
+            ),
+        )

homeassistant/components/heos/quality_scale.yaml

@@ -33,10 +33,7 @@ rules:
     status: todo
     comment: Actions currently only log and instead should raise exceptions.
   config-entry-unloading: done
-  docs-configuration-parameters:
-    status: done
-    comment: |
-      The integration doesn't provide any additional configuration parameters.
+  docs-configuration-parameters: done
   docs-installation-parameters: done
   entity-unavailable: done
   integration-owner: done

homeassistant/components/heos/strings.json

@@ -31,6 +31,28 @@
       "single_instance_allowed": "[%key:common::config_flow::abort::single_instance_allowed%]"
     }
   },
+  "options": {
+    "step": {
+      "init": {
+        "title": "HEOS Options",
+        "description": "You can sign-in to your HEOS Account to access favorites, streaming services, and other features. Clearing the credentials will sign-out of your account.",
+        "data": {
+          "username": "[%key:common::config_flow::data::username%]",
+          "password": "[%key:common::config_flow::data::password%]"
+        },
+        "data_description": {
+          "username": "The username or e-mail address of your HEOS Account.",
+          "password": "The password to your HEOS Account."
+        }
+      }
+    },
+    "error": {
+      "username_missing": "Username is missing",
+      "password_missing": "Password is missing",
+      "invalid_auth": "[%key:common::config_flow::error::invalid_auth%]",
+      "unknown": "[%key:common::config_flow::error::unknown%]"
+    }
+  },
   "services": {
     "sign_in": {
       "name": "Sign in",

tests/components/heos/conftest.py

@@ -18,21 +18,60 @@
 import pytest_asyncio
 
 from homeassistant.components import ssdp
-from homeassistant.components.heos import DOMAIN
-from homeassistant.const import CONF_HOST
+from homeassistant.components.heos import (
+    CONF_PASSWORD,
+    DOMAIN,
+    ControllerManager,
+    GroupManager,
+    HeosRuntimeData,
+    SourceManager,
+)
+from homeassistant.const import CONF_HOST, CONF_USERNAME
 
 from tests.common import MockConfigEntry
 
 
 @pytest.fixture(name="config_entry")
-def config_entry_fixture():
+def config_entry_fixture(heos_runtime_data):
     """Create a mock HEOS config entry."""
-    return MockConfigEntry(
+    entry = MockConfigEntry(
         domain=DOMAIN,
         data={CONF_HOST: "127.0.0.1"},
         title="HEOS System (via 127.0.0.1)",
         unique_id=DOMAIN,
     )
+    entry.runtime_data = heos_runtime_data
+    return entry
+
+
+@pytest.fixture(name="config_entry_options")
+def config_entry_options_fixture(heos_runtime_data):
+    """Create a mock HEOS config entry with options."""
+    entry = MockConfigEntry(
+        domain=DOMAIN,
+        data={CONF_HOST: "127.0.0.1"},
+        title="HEOS System (via 127.0.0.1)",
+        options={CONF_USERNAME: "user", CONF_PASSWORD: "pass"},
+        unique_id=DOMAIN,
+    )
+    entry.runtime_data = heos_runtime_data
+    return entry
+
+
+@pytest.fixture(name="heos_runtime_data")
+def heos_runtime_data_fixture(controller_manager, players):
+    """Create a mock HeosRuntimeData fixture."""
+    return HeosRuntimeData(
+        controller_manager, Mock(GroupManager), Mock(SourceManager), players
+    )
+
+
+@pytest.fixture(name="controller_manager")
+def controller_manager_fixture(controller):
+    """Create a mock controller manager fixture."""
+    mock_controller_manager = Mock(ControllerManager)
+    mock_controller_manager.controller = controller
+    return mock_controller_manager
 
 
 @pytest.fixture(name="controller")
@@ -43,6 +82,7 @@ def controller_fixture(
     mock_heos = Mock(Heos)
     for player in players.values():
         player.heos = mock_heos
+    mock_heos.return_value = mock_heos
     mock_heos.dispatcher = dispatcher
     mock_heos.get_players.return_value = players
     mock_heos.players = players
@@ -55,11 +95,10 @@ def controller_fixture(
     mock_heos.connection_state = const.STATE_CONNECTED
     mock_heos.get_groups.return_value = group
     mock_heos.create_group.return_value = None
-    mock = Mock(return_value=mock_heos)
 
     with (
-        patch("homeassistant.components.heos.Heos", new=mock),
-        patch("homeassistant.components.heos.config_flow.Heos", new=mock),
+        patch("homeassistant.components.heos.Heos", new=mock_heos),
+        patch("homeassistant.components.heos.config_flow.Heos", new=mock_heos),
     ):
         yield mock_heos