add 0.6.9

CHANGELOG.md

@@ -11,6 +11,28 @@ Sections:
 
 ---
 
+## [0.6.9] – 2026-01-19
+### Added
+- New Home Assistant **GUI setup** (Config Flow) – no YAML configuration required.
+- Optional **GitHub Token** support to increase API limits (up to 5000 req/h).  
+  Configurable via *Integration → Options*.
+- Clear setup guidance and warning about GitHub rate limits.
+- Automatic detection and warning if YAML setup is still present (ignored safely).
+
+### Changed
+- **store.yaml** URL is now fixed to the official Bahmcloud Store index:
+  https://git.bahmcloud.de/bahmcloud/ha_store/raw/branch/main/store.yaml
+- Installation workflow fully aligned with standard HA integrations.
+- Update platform migrated to `async_setup_entry`.
+
+### Fixed
+- Minor stability and persistence improvements in startup sequence.
+- Prevented duplicate background initialization when HA reloads the integration.
+
+### Notes
+- To enable extended GitHub access, create a fine-grained personal access token
+  (read-only) at https://github.com/settings/tokens and add it via the integration options.
+
 ## 0.6.8 – Performance & Cache Stabilization (2026-01-19)
 
 ### Fixed

custom_components/bahmcloud_store/__init__.py

@@ -3,35 +3,51 @@ from __future__ import annotations
 import logging
 from datetime import timedelta
 
+from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.components.panel_custom import async_register_panel
 from homeassistant.helpers.event import async_track_time_interval, async_call_later
 from homeassistant.const import EVENT_HOMEASSISTANT_STARTED
-from homeassistant.helpers.discovery import async_load_platform
 
 from .core import BCSCore, BCSConfig, BCSError
+from .config_flow import CONF_GITHUB_TOKEN
 
 _LOGGER = logging.getLogger(__name__)
 
 DOMAIN = "bahmcloud_store"
 
+# Fixed store index URL (not configurable by users)
 DEFAULT_STORE_URL = "https://git.bahmcloud.de/bahmcloud/ha_store/raw/branch/main/store.yaml"
-CONF_STORE_URL = "store_url"
+
+PLATFORMS: list[str] = ["update"]
+
+DATA_ENTRY = f"{DOMAIN}_entry_runtime"
 
 
 async def async_setup(hass: HomeAssistant, config: dict) -> bool:
-    cfg = config.get(DOMAIN, {}) or {}
-    store_url = cfg.get(CONF_STORE_URL, DEFAULT_STORE_URL)
+    """Set up Bahmcloud Store.
 
-    core = BCSCore(hass, BCSConfig(store_url=store_url))
+    YAML configuration is intentionally not supported.
+    Setup must happen via the UI (Config Flow).
+    """
+    if DOMAIN in (config or {}):
+        _LOGGER.warning(
+            "BCS does not support configuration.yaml setup. "
+            "Please remove 'bahmcloud_store:' from configuration.yaml and set up the integration via Settings -> Devices & Services."
+        )
+    return True
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Set up Bahmcloud Store from a config entry."""
+    token = (entry.options.get(CONF_GITHUB_TOKEN) or "").strip() or None
+
+    core = BCSCore(hass, BCSConfig(store_url=DEFAULT_STORE_URL, github_token=token))
     hass.data[DOMAIN] = core
 
     await core.async_initialize()
 
-    # Provide native Update entities in Settings -> System -> Updates.
-    # This integration is YAML-based (async_setup), therefore we load the platform manually.
-    await async_load_platform(hass, "update", DOMAIN, {}, config)
-
+    # Register HTTP views + static assets
     from .views import (
         StaticAssetsView,
         BCSApiView,
@@ -62,25 +78,29 @@ async def async_setup(hass: HomeAssistant, config: dict) -> bool:
     hass.http.register_view(BCSRestoreView(core))
     hass.http.register_view(BCSRestartView(core))
 
+    # Sidebar panel
     await async_register_panel(
         hass,
         frontend_url_path="bahmcloud-store",
         webcomponent_name="bahmcloud-store-panel",
         # IMPORTANT: bump v to avoid caching old JS
-        module_url="/api/bahmcloud_store_static/panel.js?v=108",
+        module_url="/api/bahmcloud_store_static/panel.js?v=109",
         sidebar_title="Bahmcloud Store",
         sidebar_icon="mdi:store",
         require_admin=True,
         config={},
     )
 
+    # Forward platform setup (Update entities)
+    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
+
     async def _do_startup_refresh(_now=None) -> None:
         try:
             await core.full_refresh(source="startup")
         except BCSError as e:
             _LOGGER.error("Initial refresh failed: %s", e)
 
-    # Do not block Home Assistant startup. Schedule the initial refresh after HA started.
+    # Do not block HA startup: schedule refresh after HA started.
     def _on_ha_started(_event) -> None:
         async_call_later(hass, 30, _do_startup_refresh)
 
@@ -95,6 +115,30 @@ async def async_setup(hass: HomeAssistant, config: dict) -> bool:
             _LOGGER.exception("Unexpected error during periodic refresh: %s", e)
 
     interval_seconds = int(getattr(core, "refresh_seconds", 300) or 300)
-    async_track_time_interval(hass, periodic, timedelta(seconds=interval_seconds))
+    unsub = async_track_time_interval(hass, periodic, timedelta(seconds=interval_seconds))
 
-    return True
+    # Store unload callbacks safely
+    runtimes = hass.data.setdefault(DATA_ENTRY, {})
+    runtimes[entry.entry_id] = {"unsub_interval": unsub}
+    return True
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Unload a config entry."""
+    try:
+        runtimes = hass.data.get(DATA_ENTRY, {}) or {}
+        rt = runtimes.pop(entry.entry_id, {}) if isinstance(runtimes, dict) else {}
+        unsub = rt.get("unsub_interval")
+        if callable(unsub):
+            unsub()
+    except Exception:
+        pass
+
+    unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
+    if unload_ok:
+        hass.data.pop(DOMAIN, None)
+    return unload_ok
+
+
+async def async_reload_entry(hass: HomeAssistant, entry: ConfigEntry) -> None:
+    await hass.config_entries.async_reload(entry.entry_id)

custom_components/bahmcloud_store/config_flow.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import voluptuous as vol
+
+from homeassistant import config_entries
+
+DOMAIN = "bahmcloud_store"
+
+_LOGGER = logging.getLogger(__name__)
+
+CONF_GITHUB_TOKEN = "github_token"
+
+
+class BCSConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
+    """Config flow for Bahmcloud Store.
+
+    Design goals:
+    - GUI setup only (no YAML config)
+    - store index URL is fixed (not configurable)
+    - optional GitHub token to raise API rate limits
+    """
+
+    VERSION = 1
+
+    async def async_step_user(self, user_input: dict[str, Any] | None = None):
+        """Handle the initial step."""
+        # Single instance only
+        if self._async_current_entries():
+            return self.async_abort(reason="single_instance_allowed")
+
+        if user_input is not None:
+            token = (user_input.get(CONF_GITHUB_TOKEN) or "").strip() or None
+            data: dict[str, Any] = {}
+            options: dict[str, Any] = {}
+            if token:
+                options[CONF_GITHUB_TOKEN] = token
+
+            return self.async_create_entry(title="Bahmcloud Store", data=data, options=options)
+
+        schema = vol.Schema(
+            {
+                vol.Optional(CONF_GITHUB_TOKEN, default=""): str,
+            }
+        )
+
+        return self.async_show_form(
+            step_id="user",
+            data_schema=schema,
+            description_placeholders={
+                "rate_limit": "GitHub API is rate-limited without a token (recommended for large indexes / HACS).",
+            },
+        )
+
+    @staticmethod
+    def async_get_options_flow(config_entry: config_entries.ConfigEntry):
+        return BCSOptionsFlowHandler(config_entry)
+
+
+class BCSOptionsFlowHandler(config_entries.OptionsFlow):
+    """Handle options for Bahmcloud Store."""
+
+    def __init__(self, config_entry: config_entries.ConfigEntry) -> None:
+        self.config_entry = config_entry
+
+    async def async_step_init(self, user_input: dict[str, Any] | None = None):
+        if user_input is not None:
+            token = (user_input.get(CONF_GITHUB_TOKEN) or "").strip() or None
+            opts: dict[str, Any] = dict(self.config_entry.options)
+            if token:
+                opts[CONF_GITHUB_TOKEN] = token
+            else:
+                opts.pop(CONF_GITHUB_TOKEN, None)
+            return self.async_create_entry(title="", data=opts)
+
+        cur = (self.config_entry.options.get(CONF_GITHUB_TOKEN) or "").strip()
+        schema = vol.Schema({vol.Optional(CONF_GITHUB_TOKEN, default=cur): str})
+
+        return self.async_show_form(
+            step_id="init",
+            data_schema=schema,
+            description_placeholders={
+                "rate_limit": "Optional. Adds GitHub authorization to avoid rate limits.",
+            },
+        )

custom_components/bahmcloud_store/core.py

@@ -58,6 +58,7 @@ class BCSInstallError(BCSError):
 @dataclass
 class BCSConfig:
     store_url: str
+    github_token: str | None = None
 
 
 @dataclass
@@ -696,7 +697,11 @@ class BCSCore:
 
         async def process_one(r: RepoItem) -> None:
             async with sem:
-                info: RepoInfo = await fetch_repo_info(self.hass, r.url)
+                info: RepoInfo = await fetch_repo_info(
+                    self.hass,
+                    r.url,
+                    github_token=self.config.github_token,
+                )
 
                 r.provider = info.provider or r.provider
                 r.owner = info.owner or r.owner
@@ -755,7 +760,11 @@ class BCSCore:
 
     async def _enrich_one_repo(self, r: RepoItem) -> None:
         """Fetch provider info + metadata for a single repo item."""
-        info: RepoInfo = await fetch_repo_info(self.hass, r.url)
+        info: RepoInfo = await fetch_repo_info(
+            self.hass,
+            r.url,
+            github_token=self.config.github_token,
+        )
 
         r.provider = info.provider or r.provider
         r.owner = info.owner or r.owner
@@ -807,7 +816,7 @@ class BCSCore:
             _LOGGER.debug("BCS ensure_repo_details failed for %s", repo_id, exc_info=True)
         return r
 
-    async def list_repo_versions(self, repo_id: str) -> list[dict[str, Any]]:
+    async def list_repo_versions(self, repo_id: str, *, limit: int = 20) -> list[dict[str, str]]:
         repo = self.get_repo(repo_id)
         if not repo:
             return []
@@ -826,7 +835,14 @@ class BCSCore:
             return list(cached.get("versions") or [])
 
         try:
-            versions = await fetch_repo_versions(self.hass, repo.url)
+            versions = await fetch_repo_versions(
+                self.hass,
+                repo.url,
+                provider=repo.provider,
+                default_branch=repo.default_branch,
+                github_token=self.config.github_token,
+                limit=limit,
+            )
         except Exception:
             versions = []
 
@@ -1027,23 +1043,6 @@ class BCSCore:
             default_branch=repo.default_branch,
         )
 
-    async def list_repo_versions(self, repo_id: str, *, limit: int = 20) -> list[dict[str, str]]:
-        """List installable versions/refs for a repo.
-
-        This is used by the UI to allow selecting an older tag/release.
-        """
-        repo = self.get_repo(repo_id)
-        if not repo:
-            raise BCSInstallError(f"repo_id not found: {repo_id}")
-
-        return await fetch_repo_versions(
-            self.hass,
-            repo.url,
-            provider=repo.provider,
-            default_branch=repo.default_branch,
-            limit=limit,
-        )
-
     def _pick_ref_for_install(self, repo: RepoItem) -> str:
         if repo.latest_version and str(repo.latest_version).strip():
             return str(repo.latest_version).strip()

custom_components/bahmcloud_store/manifest.json

@@ -1,7 +1,7 @@
 {
   "domain": "bahmcloud_store",
   "name": "Bahmcloud Store",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "documentation": "https://git.bahmcloud.de/bahmcloud/bahmcloud_store",
   "platforms": ["update"],
   "requirements": [],

custom_components/bahmcloud_store/providers.py

@@ -16,6 +16,17 @@ _LOGGER = logging.getLogger(__name__)
 UA = "BahmcloudStore (Home Assistant)"
 
 
+def _github_headers(github_token: str | None = None) -> dict[str, str]:
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "User-Agent": UA,
+    }
+    token = (github_token or "").strip()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
 @dataclass
 class RepoInfo:
     owner: str | None = None
@@ -189,9 +200,11 @@ async def _github_latest_version_redirect(hass: HomeAssistant, owner: str, repo:
     return None, None
 
 
-async def _github_latest_version_api(hass: HomeAssistant, owner: str, repo: str) -> tuple[str | None, str | None]:
+async def _github_latest_version_api(
+    hass: HomeAssistant, owner: str, repo: str, *, github_token: str | None = None
+) -> tuple[str | None, str | None]:
     session = async_get_clientsession(hass)
-    headers = {"Accept": "application/vnd.github+json", "User-Agent": UA}
+    headers = _github_headers(github_token)
 
     data, status = await _safe_json(session, f"https://api.github.com/repos/{owner}/{repo}/releases/latest", headers=headers)
     if isinstance(data, dict) and data.get("tag_name"):
@@ -217,12 +230,14 @@ async def _github_latest_version_api(hass: HomeAssistant, owner: str, repo: str)
     return None, None
 
 
-async def _github_latest_version(hass: HomeAssistant, owner: str, repo: str) -> tuple[str | None, str | None]:
+async def _github_latest_version(
+    hass: HomeAssistant, owner: str, repo: str, *, github_token: str | None = None
+) -> tuple[str | None, str | None]:
     tag, src = await _github_latest_version_redirect(hass, owner, repo)
     if tag:
         return tag, src
 
-    tag, src = await _github_latest_version_api(hass, owner, repo)
+    tag, src = await _github_latest_version_api(hass, owner, repo, github_token=github_token)
     if tag:
         return tag, src
 
@@ -316,7 +331,7 @@ async def _gitlab_latest_version(
     return None, None
 
 
-async def fetch_repo_info(hass: HomeAssistant, repo_url: str) -> RepoInfo:
+async def fetch_repo_info(hass: HomeAssistant, repo_url: str, *, github_token: str | None = None) -> RepoInfo:
     provider = detect_provider(repo_url)
     owner, repo = _split_owner_repo(repo_url)
 
@@ -337,7 +352,7 @@ async def fetch_repo_info(hass: HomeAssistant, repo_url: str) -> RepoInfo:
 
     try:
         if provider == "github":
-            headers = {"Accept": "application/vnd.github+json", "User-Agent": UA}
+            headers = _github_headers(github_token)
             data, status = await _safe_json(session, f"https://api.github.com/repos/{owner}/{repo}", headers=headers)
 
             if isinstance(data, dict):
@@ -356,7 +371,7 @@ async def fetch_repo_info(hass: HomeAssistant, repo_url: str) -> RepoInfo:
                 if desc:
                     info.description = desc
 
-            ver, src = await _github_latest_version(hass, owner, repo)
+            ver, src = await _github_latest_version(hass, owner, repo, github_token=github_token)
             info.latest_version = ver
             info.latest_version_source = src
             return info
@@ -514,6 +529,7 @@ async def fetch_repo_versions(
     provider: str | None = None,
     default_branch: str | None = None,
     limit: int = 20,
+    github_token: str | None = None,
 ) -> list[dict[str, str]]:
     """List available versions/refs for a repository.
 
@@ -560,7 +576,7 @@ async def fetch_repo_versions(
     try:
         if prov == "github":
             # Releases
-            gh_headers = {"Accept": "application/vnd.github+json", "User-Agent": UA}
+            gh_headers = _github_headers(github_token)
             data, _ = await _safe_json(
                 session,
                 f"https://api.github.com/repos/{owner}/{repo}/releases?per_page={int(limit)}",

custom_components/bahmcloud_store/strings.json

@@ -1,4 +1,29 @@
 {
+  "config": {
+    "abort": {
+      "single_instance_allowed": "Bahmcloud Store is already configured."
+    },
+    "step": {
+      "user": {
+        "title": "Set up Bahmcloud Store",
+        "description": "The store index is fixed to the official Bahmcloud Store.\n\nOptional: Add a GitHub token to increase API rate limits for GitHub/HACS repositories.",
+        "data": {
+          "github_token": "GitHub token (optional)"
+        }
+      }
+    }
+  },
+  "options": {
+    "step": {
+      "init": {
+        "title": "Bahmcloud Store options",
+        "description": "Optional: Configure a GitHub token to increase API rate limits.",
+        "data": {
+          "github_token": "GitHub token (optional)"
+        }
+      }
+    }
+  },
   "issues": {
     "restart_required": {
       "title": "Restart required",

custom_components/bahmcloud_store/update.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from typing import Any
 
 from homeassistant.components.update import UpdateEntity, UpdateEntityFeature
+from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers.dispatcher import async_dispatcher_connect
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
@@ -139,13 +140,8 @@ def _sync_entities(core: BCSCore, existing: dict[str, BCSRepoUpdateEntity], asyn
         ent.async_write_ha_state()
 
 
-async def async_setup_platform(
-    hass: HomeAssistant,
-    config,
-    async_add_entities: AddEntitiesCallback,
-    discovery_info=None,
-):
-    """Set up BCS update entities."""
+async def _async_setup(hass: HomeAssistant, async_add_entities: AddEntitiesCallback) -> None:
+    """Common update entity setup for both config entries and legacy YAML."""
     core: BCSCore | None = hass.data.get(DOMAIN)
     if not core:
         _LOGGER.debug("BCS core not available, skipping update platform setup")
@@ -159,4 +155,23 @@ async def async_setup_platform(
     def _handle_update() -> None:
         _sync_entities(core, entities, async_add_entities)
 
-    async_dispatcher_connect(hass, SIGNAL_UPDATED, _handle_update)
+    async_dispatcher_connect(hass, SIGNAL_UPDATED, _handle_update)
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: ConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up update entities from a config entry."""
+    await _async_setup(hass, async_add_entities)
+
+
+async def async_setup_platform(
+    hass: HomeAssistant,
+    config,
+    async_add_entities: AddEntitiesCallback,
+    discovery_info=None,
+):
+    """Legacy YAML setup (not supported, kept for safety)."""
+    await _async_setup(hass, async_add_entities)