Switch drift alerting from persistent notifications to repair issues

Replace all persistent_notification usage with Home Assistant repair
issues for better UX. Add coordinator poll failure alerting that
creates a repair issue after 12 consecutive failures and auto-dismisses
on recovery.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: raman325

custom_components/lock_code_manager/const.py

@@ -108,6 +108,9 @@
 BACKOFF_INITIAL_SECONDS: int = 60
 BACKOFF_MAX_SECONDS: int = 1800  # 30 minutes
 
+# Poll failure alerting
+POLL_FAILURE_ALERT_THRESHOLD: int = 12
+
 # Sync timing
 TICK_INTERVAL = timedelta(seconds=5)
 MAX_SYNC_ATTEMPTS = 3

custom_components/lock_code_manager/coordinator.py

@@ -13,6 +13,11 @@
 from homeassistant.const import CONF_ENABLED, CONF_PIN
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers.event import async_track_time_interval
+from homeassistant.helpers.issue_registry import (
+    IssueSeverity,
+    async_create_issue,
+    async_delete_issue,
+)
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
 
 from .const import (
@@ -21,6 +26,7 @@
     BACKOFF_MAX_SECONDS,
     CONF_SLOTS,
     DOMAIN,
+    POLL_FAILURE_ALERT_THRESHOLD,
 )
 from .data import get_entry_data
 from .exceptions import LockCodeManagerError
@@ -136,9 +142,25 @@ def _apply_backoff(self) -> None:
                     self._lock.lock.entity_id,
                 )
 
+        if self._consecutive_failures == POLL_FAILURE_ALERT_THRESHOLD:
+            async_create_issue(
+                self.hass,
+                DOMAIN,
+                f"lock_offline_{self._lock.lock.entity_id}",
+                is_fixable=False,
+                is_persistent=False,
+                severity=IssueSeverity.WARNING,
+                translation_key="lock_offline",
+                translation_placeholders={
+                    "lock_entity_id": self._lock.lock.entity_id,
+                    "failure_count": str(self._consecutive_failures),
+                },
+            )
+
     def _reset_backoff(self) -> None:
         """Reset failure counter and restore original update interval."""
         if self._consecutive_failures > 0:
+            had_alert = self._consecutive_failures >= POLL_FAILURE_ALERT_THRESHOLD
             _LOGGER.info(
                 "Lock %s recovered after %d consecutive failures",
                 self._lock.lock.entity_id,
@@ -147,6 +169,12 @@ def _reset_backoff(self) -> None:
             self._consecutive_failures = 0
             if self._original_update_interval is not None:
                 self.update_interval = self._original_update_interval
+            if had_alert:
+                async_delete_issue(
+                    self.hass,
+                    DOMAIN,
+                    f"lock_offline_{self._lock.lock.entity_id}",
+                )
 
     async def async_get_usercodes(self) -> dict[int, str | SlotCode]:
         """Update usercodes."""

custom_components/lock_code_manager/repairs.py

@@ -9,6 +9,18 @@
 from .const import CONF_NUMBER_OF_USES, CONF_SLOTS, DOMAIN
 
 
+class AcknowledgeRepairFlow(RepairsFlow):
+    """Simple repair flow that just acknowledges the issue."""
+
+    async def async_step_init(
+        self, user_input: dict[str, str] | None = None
+    ) -> data_entry_flow.FlowResult:
+        """Handle the confirm step."""
+        if user_input is not None:
+            return self.async_create_entry(title="", data={})
+        return self.async_show_form(step_id="init")
+
+
 class NumberOfUsesDeprecatedFlow(RepairsFlow):
     """Handler for the number_of_uses deprecation repair.
 
@@ -54,4 +66,6 @@ async def async_create_fix_flow(
     """Create a fix flow for a repair issue."""
     if issue_id == "number_of_uses_deprecated":
         return NumberOfUsesDeprecatedFlow()
+    if issue_id.startswith("slot_disabled_") or issue_id.startswith("pin_required_"):
+        return AcknowledgeRepairFlow()
     raise ValueError(f"Unknown issue: {issue_id}")

custom_components/lock_code_manager/strings.json

@@ -140,6 +140,32 @@
           }
         }
       }
+    },
+    "slot_disabled": {
+      "title": "Lock Code Manager: Slot {slot_num} disabled",
+      "fix_flow": {
+        "step": {
+          "init": {
+            "title": "Slot {slot_num} was disabled",
+            "description": "Slot {slot_num} has been automatically disabled.\n\n**Reason:** {reason}\n\nClick **Submit** to acknowledge this issue."
+          }
+        }
+      }
+    },
+    "pin_required": {
+      "title": "Lock Code Manager: PIN required for slot {slot_num}",
+      "fix_flow": {
+        "step": {
+          "init": {
+            "title": "PIN required for slot {slot_num}",
+            "description": "A PIN is required to enable slot {slot_num} on the lock configuration **{config_entry_title}**. Please set a PIN before enabling this slot.\n\nClick **Submit** to acknowledge this issue."
+          }
+        }
+      }
+    },
+    "lock_offline": {
+      "title": "Lock unreachable: {lock_entity_id}",
+      "description": "Lock Code Manager has been unable to communicate with `{lock_entity_id}` for {failure_count} consecutive attempts. Code synchronization is paused until the lock is reachable again. This issue will be automatically dismissed when the lock recovers."
     }
   }
 }

custom_components/lock_code_manager/switch.py

@@ -4,12 +4,12 @@
 
 import logging
 
-from homeassistant.components.persistent_notification import async_create
 from homeassistant.components.switch import SwitchEntity
 from homeassistant.const import CONF_ENABLED, CONF_PIN, STATE_UNKNOWN, Platform
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers import entity_registry as er
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from homeassistant.helpers.issue_registry import IssueSeverity, async_create_issue
 
 from .const import DOMAIN
 from .entity import BaseLockCodeManagerEntity
@@ -64,14 +64,18 @@ async def async_turn_on(self, **kwargs) -> None:
             and (state := self.hass.states.get(self._pin_entity_id))
             and state.state in (None, "", STATE_UNKNOWN)
         ):
-            async_create(
+            async_create_issue(
                 self.hass,
-                (
-                    f"PIN is required to enable slot {self.slot_num} on the lock "
-                    f"configuration {self.config_entry.title}."
-                ),
-                "Problem with Lock Code Manager",
-                f"{DOMAIN}_{self.config_entry.entry_id}_{self.slot_num}_pin_required",
+                DOMAIN,
+                f"pin_required_{self.config_entry.entry_id}_{self.slot_num}",
+                is_fixable=True,
+                is_persistent=True,
+                severity=IssueSeverity.WARNING,
+                translation_key="pin_required",
+                translation_placeholders={
+                    "slot_num": str(self.slot_num),
+                    "config_entry_title": self.config_entry.title,
+                },
             )
             return
         self._update_config_entry(True)

custom_components/lock_code_manager/sync.py

@@ -299,15 +299,14 @@ async def _perform_sync(self, slot_state: SlotState) -> None:
             self._last_set_pin = None
             _LOGGER.debug("%s: Cleared usercode", self._log_prefix)
 
-    async def _disable_slot(self, reason: str, title: str) -> None:
-        """Disable the slot and create a persistent notification."""
+    async def _disable_slot(self, reason: str) -> None:
+        """Disable the slot and create a repair issue."""
         await async_disable_slot(
             self._hass,
             self._ent_reg,
             self._config_entry.entry_id,
             self._slot_num,
             reason=reason,
-            title=title,
             lock_name=self._lock.display_name,
             lock_entity_id=self._lock.lock.entity_id,
         )
@@ -484,7 +483,6 @@ async def _async_tick_impl(self) -> None:
                     f"The lock may be rejecting the code silently. "
                     f"Slot {self._slot_num} has been disabled. Check the "
                     f"code and re-enable the slot.",
-                    title="Lock Code Sync Failed",
                 )
                 return
 
@@ -497,7 +495,6 @@ async def _async_tick_impl(self) -> None:
                     f"Lock **{err.lock_entity_id}**: slot **{err.code_slot}** "
                     f"has been disabled. {err}\n\n"
                     f"Fix the issue and re-enable the slot.",
-                    title="Lock Code Rejected",
                 )
                 return
             except LockDisconnected as err:
@@ -525,7 +522,6 @@ async def _async_tick_impl(self) -> None:
                     f"encountered an unexpected error during sync. This may indicate a bug "
                     f"in the lock code manager integration. Check logs for details and "
                     f"report this issue.\n\nError: {type(err).__name__}: {err}",
-                    title="Lock Code Sync Error",
                 )
                 return
             else:

custom_components/lock_code_manager/translations/en.json

@@ -140,6 +140,32 @@
           }
         }
       }
+    },
+    "slot_disabled": {
+      "title": "Lock Code Manager: Slot {slot_num} disabled",
+      "fix_flow": {
+        "step": {
+          "init": {
+            "title": "Slot {slot_num} was disabled",
+            "description": "Slot {slot_num} has been automatically disabled.\n\n**Reason:** {reason}\n\nClick **Submit** to acknowledge this issue."
+          }
+        }
+      }
+    },
+    "pin_required": {
+      "title": "Lock Code Manager: PIN required for slot {slot_num}",
+      "fix_flow": {
+        "step": {
+          "init": {
+            "title": "PIN required for slot {slot_num}",
+            "description": "A PIN is required to enable slot {slot_num} on the lock configuration **{config_entry_title}**. Please set a PIN before enabling this slot.\n\nClick **Submit** to acknowledge this issue."
+          }
+        }
+      }
+    },
+    "lock_offline": {
+      "title": "Lock unreachable: {lock_entity_id}",
+      "description": "Lock Code Manager has been unable to communicate with `{lock_entity_id}` for {failure_count} consecutive attempts. Code synchronization is paused until the lock is reachable again. This issue will be automatically dismissed when the lock recovers."
     }
   }
 }

custom_components/lock_code_manager/util.py

@@ -9,12 +9,12 @@
 from typing import Any
 import zlib
 
-from homeassistant.components.persistent_notification import async_create
 from homeassistant.components.switch import DOMAIN as SWITCH_DOMAIN, SERVICE_TURN_OFF
 from homeassistant.const import ATTR_ENTITY_ID, CONF_ENABLED
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers import entity_registry as er
 from homeassistant.helpers.event import async_call_later
+from homeassistant.helpers.issue_registry import IssueSeverity, async_create_issue
 
 from .const import DOMAIN
 from .data import build_slot_unique_id
@@ -43,15 +43,14 @@ async def async_disable_slot(
     slot_num: int,
     *,
     reason: str | None = None,
-    title: str = "Lock Code Manager: Slot Disabled",
     lock_name: str | None = None,
     lock_entity_id: str | None = None,
 ) -> bool:
-    """Disable a slot via the enabled switch and optionally create a notification.
+    """Disable a slot via the enabled switch and optionally create a repair issue.
 
     Returns True if the switch was found and turned off, False otherwise.
-    When reason is provided, a persistent notification is created with the
-    given title.
+    When reason is provided, a repair issue is created so the user can
+    acknowledge it through the Home Assistant repairs dashboard.
     """
     enabled_entity_id = ent_reg.async_get_entity_id(
         SWITCH_DOMAIN,
@@ -75,11 +74,21 @@ async def async_disable_slot(
     )
 
     if reason:
-        async_create(
+        issue_id = (
+            f"slot_disabled_{config_entry_id}_{slot_num}_{lock_entity_id or 'unknown'}"
+        )
+        async_create_issue(
             hass,
-            reason,
-            title=title,
-            notification_id=f"{DOMAIN}_{config_entry_id}_{slot_num}_slot_disabled",
+            DOMAIN,
+            issue_id,
+            is_fixable=True,
+            is_persistent=True,
+            severity=IssueSeverity.WARNING,
+            translation_key="slot_disabled",
+            translation_placeholders={
+                "slot_num": str(slot_num),
+                "reason": reason,
+            },
         )
 
     return True

tests/providers/test_zwave_js.py

@@ -16,14 +16,12 @@
 from zwave_js_server.event import Event as ZwaveEvent
 from zwave_js_server.model.node import Node
 
-from homeassistant.components.persistent_notification import (
-    _async_get_or_create_notifications,
-)
 from homeassistant.components.zwave_js.const import DOMAIN as ZWAVE_JS_DOMAIN
 from homeassistant.config_entries import ConfigEntryState
 from homeassistant.const import CONF_ENABLED, CONF_NAME, CONF_PIN, STATE_ON
 from homeassistant.core import Event, HomeAssistant, callback
 from homeassistant.helpers import device_registry as dr, entity_registry as er
+from homeassistant.helpers.issue_registry import async_get as async_get_issue_registry
 
 from custom_components.lock_code_manager.const import (
     ATTR_ACTION_TEXT,
@@ -1910,10 +1908,14 @@ async def test_duplicate_code_notification_ignored_when_not_in_progress(
     # Switch should still be on
     assert hass.states.get(switch_entity_id).state == STATE_ON
 
-    # No persistent notification
-    notifications = _async_get_or_create_notifications(hass)
-    notification_id = f"{DOMAIN}_{lcm_entry.entry_id}_2_slot_disabled"
-    assert notification_id not in notifications
+    # No repair issue created for slot_disabled
+    issue_registry = async_get_issue_registry(hass)
+    matching_issues = [
+        issue
+        for issue in issue_registry.issues.values()
+        if issue.domain == DOMAIN and issue.issue_id.startswith("slot_disabled_")
+    ]
+    assert len(matching_issues) == 0
 
     await hass.config_entries.async_unload(lcm_entry.entry_id)