Add Homecast integration

Add a new integration for Homecast, which bridges Apple HomeKit smart
home devices to open standards. The integration connects to the Homecast
cloud API via OAuth 2.1 with PKCE and exposes HomeKit light devices as
native Home Assistant light entities.

Features:
- OAuth 2.1 with PKCE authentication
- Automatic token refresh during polling
- Auth error detection triggers reauth flow
- Light platform: on/off, brightness, HS color, color temperature
- Cloud polling every 30 seconds with optimistic updates

Uses pyhomecast (PyPI) as the third-party API client library.
Additional platforms (switch, climate, lock, etc.) will follow in
subsequent PRs.

Author: robjampar

CODEOWNERS

@@ -0,0 +1,87 @@
+"""The Homecast integration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+
+from pyhomecast import HomecastClient
+
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.const import CONF_ACCESS_TOKEN, Platform
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import (
+    ConfigEntryAuthFailed,
+    ConfigEntryNotReady,
+    OAuth2TokenRequestError,
+    OAuth2TokenRequestReauthError,
+)
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
+from homeassistant.helpers.config_entry_oauth2_flow import (
+    OAuth2Session,
+    async_get_config_entry_implementation,
+)
+
+from .const import API_BASE_URL, DOMAIN as DOMAIN
+from .coordinator import HomecastCoordinator
+
+_LOGGER = logging.getLogger(__name__)
+
+PLATFORMS = [
+    Platform.LIGHT,
+]
+
+
+@dataclass
+class HomecastData:
+    """Runtime data for a Homecast config entry."""
+
+    coordinator: HomecastCoordinator
+    client: HomecastClient
+
+
+type HomecastConfigEntry = ConfigEntry[HomecastData]
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: HomecastConfigEntry) -> bool:
+    """Set up Homecast from a config entry."""
+    implementation = await async_get_config_entry_implementation(hass, entry)
+    session = OAuth2Session(hass, entry, implementation)
+
+    try:
+        await session.async_ensure_token_valid()
+    except OAuth2TokenRequestReauthError as err:
+        raise ConfigEntryAuthFailed from err
+    except OAuth2TokenRequestError as err:
+        raise ConfigEntryNotReady from err
+
+    client = HomecastClient(session=async_get_clientsession(hass), api_url=API_BASE_URL)
+    client.authenticate(session.token[CONF_ACCESS_TOKEN])
+
+    async def _refresh_token() -> None:
+        await session.async_ensure_token_valid()
+        client.authenticate(session.token[CONF_ACCESS_TOKEN])
+
+    coordinator = HomecastCoordinator(hass, client, _refresh_token)
+
+    try:
+        await coordinator.async_config_entry_first_refresh()
+    except ConfigEntryAuthFailed:
+        raise
+    except Exception as err:
+        raise ConfigEntryNotReady(
+            f"Could not fetch initial state from Homecast: {err}"
+        ) from err
+
+    entry.runtime_data = HomecastData(
+        coordinator=coordinator,
+        client=client,
+    )
+
+    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
+    return True
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: HomecastConfigEntry) -> bool:
+    """Unload a Homecast config entry."""
+    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)

homeassistant/components/homecast/__init__.py

@@ -0,0 +1,47 @@
+"""OAuth application credentials for Homecast."""
+
+from __future__ import annotations
+
+from homeassistant.components.application_credentials import (
+    AuthorizationServer,
+    ClientCredential,
+)
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.config_entry_oauth2_flow import (
+    LocalOAuth2ImplementationWithPkce,
+)
+
+from .const import OAUTH_AUTHORIZE_URL, OAUTH_TOKEN_URL, SCOPES
+
+
+async def async_get_authorization_server(hass: HomeAssistant) -> AuthorizationServer:
+    """Return the Homecast authorization server."""
+    return AuthorizationServer(
+        authorize_url=OAUTH_AUTHORIZE_URL,
+        token_url=OAUTH_TOKEN_URL,
+    )
+
+
+async def async_get_auth_implementation(
+    hass: HomeAssistant, auth_domain: str, credential: ClientCredential
+) -> HomecastOAuth2Implementation:
+    """Return a custom auth implementation with PKCE."""
+    return HomecastOAuth2Implementation(
+        hass,
+        auth_domain,
+        credential.client_id,
+        OAUTH_AUTHORIZE_URL,
+        OAUTH_TOKEN_URL,
+        credential.client_secret,
+    )
+
+
+class HomecastOAuth2Implementation(LocalOAuth2ImplementationWithPkce):
+    """Homecast OAuth2 implementation with PKCE (S256)."""
+
+    @property
+    def extra_authorize_data(self) -> dict:
+        """Extra data that needs to be appended to the authorize url."""
+        return super().extra_authorize_data | {
+            "scope": SCOPES,
+        }

homeassistant/components/homecast/application_credentials.py

@@ -0,0 +1,78 @@
+"""Config flow for Homecast."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import logging
+from typing import Any
+
+from pyhomecast import HomecastAuthError, HomecastClient, HomecastConnectionError
+
+from homeassistant.config_entries import SOURCE_REAUTH, ConfigFlowResult
+from homeassistant.const import CONF_ACCESS_TOKEN, CONF_TOKEN
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
+from homeassistant.helpers.config_entry_oauth2_flow import AbstractOAuth2FlowHandler
+
+from .const import API_BASE_URL, DOMAIN, SCOPES
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class HomecastFlowHandler(AbstractOAuth2FlowHandler, domain=DOMAIN):
+    """Handle a config flow for Homecast."""
+
+    DOMAIN = DOMAIN
+
+    @property
+    def logger(self) -> logging.Logger:
+        """Return logger."""
+        return _LOGGER
+
+    @property
+    def extra_authorize_data(self) -> dict[str, Any]:
+        """Extra data to include in the authorize URL."""
+        return {"scope": SCOPES}
+
+    async def async_step_reauth(
+        self, entry_data: Mapping[str, Any]
+    ) -> ConfigFlowResult:
+        """Handle re-authentication."""
+        return await self.async_step_reauth_confirm()
+
+    async def async_step_reauth_confirm(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Confirm re-authentication."""
+        if user_input is None:
+            return self.async_show_form(step_id="reauth_confirm")
+        return await self.async_step_user()
+
+    async def async_oauth_create_entry(self, data: dict[str, Any]) -> ConfigFlowResult:
+        """Create an entry after OAuth flow completes."""
+        token = data[CONF_TOKEN][CONF_ACCESS_TOKEN]
+        client = HomecastClient(
+            session=async_get_clientsession(self.hass), api_url=API_BASE_URL
+        )
+        client.authenticate(token)
+
+        try:
+            state = await client.get_state()
+        except HomecastAuthError:
+            return self.async_abort(reason="invalid_auth")
+        except HomecastConnectionError:
+            return self.async_abort(reason="cannot_connect")
+        except Exception:
+            _LOGGER.exception("Unexpected error during Homecast setup")
+            return self.async_abort(reason="unknown")
+
+        _LOGGER.info("Homecast connected: found %d home(s)", len(state.homes))
+
+        await self.async_set_unique_id(DOMAIN)
+
+        if self.source == SOURCE_REAUTH:
+            return self.async_update_reload_and_abort(
+                self._get_reauth_entry(), data_updates=data
+            )
+
+        self._abort_if_unique_id_configured()
+        return self.async_create_entry(title="Homecast", data=data)

homeassistant/components/homecast/config_flow.py

@@ -0,0 +1,11 @@
+"""Constants for the Homecast integration."""
+
+DOMAIN = "homecast"
+
+API_BASE_URL = "https://api.homecast.cloud"
+OAUTH_AUTHORIZE_URL = f"{API_BASE_URL}/oauth/authorize"
+OAUTH_TOKEN_URL = f"{API_BASE_URL}/oauth/token"
+
+SCOPES = "mcp:read mcp:write"
+
+UPDATE_INTERVAL = 30

homeassistant/components/homecast/const.py

@@ -0,0 +1,59 @@
+"""DataUpdateCoordinator for Homecast."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine
+from datetime import timedelta
+import logging
+from typing import Any
+
+from pyhomecast import (
+    HomecastAuthError,
+    HomecastClient,
+    HomecastConnectionError,
+    HomecastState,
+)
+
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import ConfigEntryAuthFailed
+from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
+
+from .const import DOMAIN, UPDATE_INTERVAL
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class HomecastCoordinator(DataUpdateCoordinator[HomecastState]):
+    """Coordinator that polls the Homecast REST API for device state."""
+
+    def __init__(
+        self,
+        hass: HomeAssistant,
+        client: HomecastClient,
+        refresh_token: Callable[[], Coroutine[Any, Any, None]],
+    ) -> None:
+        """Initialize the coordinator."""
+        super().__init__(
+            hass,
+            _LOGGER,
+            name=DOMAIN,
+            update_interval=timedelta(seconds=UPDATE_INTERVAL),
+        )
+        self.client = client
+        self._refresh_token = refresh_token
+
+    async def _async_update_data(self) -> HomecastState:
+        """Fetch state from the Homecast API."""
+        try:
+            await self._refresh_token()
+            return await self.client.get_state()
+        except HomecastAuthError as err:
+            raise ConfigEntryAuthFailed from err
+        except HomecastConnectionError as err:
+            raise UpdateFailed(f"Error communicating with Homecast: {err}") from err
+
+    async def async_set_state(self, updates: dict[str, Any]) -> None:
+        """Send a state update and request a refresh."""
+        await self._refresh_token()
+        await self.client.set_state(updates)
+        await self.async_request_refresh()

homeassistant/components/homecast/coordinator.py

@@ -0,0 +1,74 @@
+"""Base entity for Homecast."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyhomecast import HomecastDevice
+
+from homeassistant.helpers.device_registry import DeviceInfo
+from homeassistant.helpers.update_coordinator import CoordinatorEntity
+
+from .const import DOMAIN
+from .coordinator import HomecastCoordinator
+
+
+class HomecastEntity(CoordinatorEntity[HomecastCoordinator]):
+    """Base class for Homecast entities."""
+
+    _attr_has_entity_name = True
+
+    def __init__(
+        self,
+        coordinator: HomecastCoordinator,
+        device: HomecastDevice,
+    ) -> None:
+        """Initialize the entity."""
+        super().__init__(coordinator)
+        self._device_id = device.unique_id
+        self._attr_unique_id = device.unique_id
+
+        # Prefix room name with home name when there are multiple homes
+        multiple_homes = (
+            coordinator.data is not None and len(coordinator.data.homes) > 1
+        )
+        area = (
+            f"{device.home_name} - {device.room_name}"
+            if multiple_homes
+            else device.room_name
+        )
+
+        self._attr_device_info = DeviceInfo(
+            identifiers={(DOMAIN, device.unique_id)},
+            name=device.name,
+            manufacturer="Homecast (HomeKit)",
+            model=device.device_type.replace("_", " ").title(),
+            suggested_area=area,
+        )
+
+    @property
+    def device(self) -> HomecastDevice | None:
+        """Return the current device data from the coordinator."""
+        if self.coordinator.data is None:
+            return None
+        return self.coordinator.data.devices.get(self._device_id)
+
+    @property
+    def available(self) -> bool:
+        """Return True if the device is available."""
+        return super().available and self.device is not None
+
+    async def _async_set_state(self, props: dict[str, Any]) -> None:
+        """Send a state update for this device."""
+        device = self.device
+        if device is None:
+            return
+        await self.coordinator.async_set_state(
+            {
+                device.home_key: {
+                    device.room_key: {
+                        device.accessory_key: props,
+                    },
+                },
+            }
+        )