Block Owner/Service-only writes and warn on insufficient role (fixes #311)

README.md

@@ -46,6 +46,18 @@ Confirmed to work with Zaptec products
   * Disable [Zaptec Sense](https://help.zaptec.com/hc/en-GB/article/how-to-manage-zaptec-sense-in-the-zaptec-portal) (aka APM/Automatic Power Management).
   * Disable [stand-alone mode](https://help.zaptec.com/hc/en-GB/article/use-stand-alone-mode-for-troubleshooting-and-unstable-internet).
 
+> [!NOTE]
+> If the configured account only has the _User_ role on an installation, the
+> integration still sets up and works normally for everything that doesn't
+> need Owner/Service access (see [Known issues](#known-issues)). Trying to
+> change the available current, the 3-to-1 phase switch current, a charger's
+> settings, or send a charger command (e.g. restart) will fail with a clear
+> error instead of a raw HTTP 403, and Home Assistant will show
+> a persistent notice under *Settings → Repairs* naming the affected
+> installation and the role it needs. If this is expected for your setup,
+> you can dismiss it with "Ignore" in the Repairs list — it won't come back
+> unless the account's role actually changes.
+
 # Known issues
 
 * Sending a _"deauthorize_and_stop"_ command will give an error. This is due to
@@ -61,6 +73,14 @@ Confirmed to work with Zaptec products
   a workaround is to use the more frequently updated _Session total charge_ entity instead. This reduces the delay-issue,
   but has a separate drawback where a restart of Home Assistant during a charging session can give a fake spike in the logged
   consumption that needs to be manually edited using "Adjust sum" in the Statistics tab of the Developer tools dashboard.
+* A Zaptec Portal user with only the _User_ role (no _Owner_ or _Service_) has
+  significantly reduced access: the installation hierarchy, firmware info,
+  individual charger detail/state, and the live update stream are all blocked
+  by the Zaptec API itself, and this integration additionally blocks changing
+  installation-level current limits, charger settings, and charger commands
+  (see [Requirements](#requirements)). Online/offline status and operating
+  mode keep working, since those are
+  included in the basic charger list the API returns regardless of role.
 
 
 # Installation and setup

custom_components/zaptec/__init__.py

@@ -26,16 +26,39 @@
 from .manager import ZaptecConfigEntry, ZaptecManager
 from .services import async_setup_services, async_unload_services
 from .zaptec import (
+    RETRYABLE_HTTP_STATUSES,
     AuthenticationError,
     Installation,
     RequestConnectionError,
+    RequestError,
     RequestTimeoutError,
     Zaptec,
     ZaptecApiError,
 )
 
 _LOGGER = logging.getLogger(__name__)
 
+
+def _config_entry_error(
+    err: ZaptecApiError,
+) -> ConfigEntryAuthFailed | ConfigEntryNotReady | ConfigEntryError:
+    """Map a Zaptec API error from setup login to a HA config-entry error.
+
+    Authentication failures are non-recoverable (trigger re-auth). Connection
+    and timeout errors, and transient server statuses (429/502/503/504), are
+    recoverable, so we raise ConfigEntryNotReady to let Home Assistant retry
+    setup automatically instead of failing permanently (issue #392). All other
+    API errors remain permanent ConfigEntryError failures.
+    """
+    if isinstance(err, AuthenticationError):
+        return ConfigEntryAuthFailed(str(err))
+    if isinstance(err, (RequestTimeoutError, RequestConnectionError)):
+        return ConfigEntryNotReady(str(err))
+    if isinstance(err, RequestError) and err.error_code in RETRYABLE_HTTP_STATUSES:
+        return ConfigEntryNotReady(str(err))
+    return ConfigEntryError(str(err))
+
+
 PLATFORMS = [
     Platform.BINARY_SENSOR,
     Platform.BUTTON,
@@ -80,15 +103,9 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     # Login to the Zaptec account
     try:
         await zaptec.login()
-    except AuthenticationError as err:
-        _LOGGER.error("Authentication failed: %s", err)
-        raise ConfigEntryAuthFailed from err
-    except (RequestTimeoutError, RequestConnectionError) as err:
-        _LOGGER.error("Connection error: %s", err)
-        raise ConfigEntryNotReady from err
     except ZaptecApiError as err:
-        _LOGGER.error("Zaptec API error: %s", err)
-        raise ConfigEntryError from err
+        _LOGGER.error("Zaptec login failed: %s", err)
+        raise _config_entry_error(err) from err
 
     # Get the structure of devices from Zaptec and determine the zaptec objects to track
     tracked_devices = await ZaptecManager.first_time_setup(

custom_components/zaptec/coordinator.py

@@ -9,6 +9,7 @@
 from typing import TYPE_CHECKING
 
 from homeassistant.core import HomeAssistant
+from homeassistant.helpers import issue_registry as ir
 from homeassistant.helpers.debounce import Debouncer
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
 
@@ -121,6 +122,50 @@ async def _async_update_data(self) -> None:
             _LOGGER.exception("Fetching data failed")
             raise UpdateFailed(err) from err
 
+        if isinstance(self.options.zaptec_object, Installation):
+            self._check_installation_role(self.options.zaptec_object)
+
+    def _check_installation_role(self, installation: Installation) -> None:
+        """Create or clear a Repair issue for insufficient write access.
+
+        `installation/update` requires the Owner or Service role
+        (https://docs.zaptec.com/reference/api_installation_id_update_post).
+        If CurrentUserRoles hasn't been observed yet, leave any existing issue
+        alone rather than guessing.
+
+        Deliberately calling async_create_issue() again every poll (rather
+        than only on the first observation) is safe and intentional: HA's
+        issue registry replaces the existing IssueEntry in place and does not
+        touch dismissed_version, so a user who has clicked "Ignore" on this
+        issue in Settings > Repairs stays ignored across every subsequent
+        poll as long as the role doesn't change. Only deleting the issue
+        (role becomes sufficient) and later recreating it (role becomes
+        insufficient again) resets that dismissal -- which is intentional,
+        since a real role change deserves fresh attention.
+        """
+        roles = installation.get("current_user_roles")
+        if roles is None:
+            return
+
+        issue_id = f"insufficient_role_{installation.id}"
+        if "Owner" in roles or "Maintainer" in roles:
+            ir.async_delete_issue(self.hass, DOMAIN, issue_id)
+            return
+
+        ir.async_create_issue(
+            self.hass,
+            DOMAIN,
+            issue_id,
+            is_fixable=False,
+            severity=ir.IssueSeverity.WARNING,
+            translation_key="insufficient_role",
+            translation_placeholders={
+                "installation_name": str(installation.get("name", installation.qual_id)),
+                "role": roles or "None",
+            },
+            learn_more_url="https://portal.zaptec.com/",
+        )
+
     async def _trigger_poll(self, zaptec_obj: ZaptecBase) -> None:
         """Trigger a poll update sequence for the given object.
 

custom_components/zaptec/services.yaml

@@ -73,7 +73,7 @@ restart_charger:
       description: Charger identifier
       example: 00000000-1111-2222-3333-444444444444
 
-update_firmware:
+upgrade_firmware:
   name: Update firmware
   description: >-
     Send update firmware request to the charger. Select charger

custom_components/zaptec/translations/en.json

@@ -192,5 +192,11 @@
                 "name": "Firmware update"
             }
         }
+    },
+    "issues": {
+        "insufficient_role": {
+            "title": "Limited access to {installation_name}",
+            "description": "The Zaptec account used by this integration only has the following role(s) on installation \"{installation_name}\": {role}. Changing the available current or the 3-to-1 phase switch current requires the Owner or Service role.\n\nTo enable these controls, grant Owner or Service access for this installation to this account in the Zaptec Portal."
+        }
     }
 }

custom_components/zaptec/translations/nb.json

@@ -192,5 +192,11 @@
                 "name": "Fastvareoppdatering"
             }
         }
+    },
+    "issues": {
+        "insufficient_role": {
+            "title": "Begrenset tilgang til {installation_name}",
+            "description": "Zaptec-kontoen som brukes av denne integrasjonen har kun følgende rolle(r) på installasjonen «{installation_name}»: {role}. Å endre tilgjengelig strøm eller 3-til-1-fase bytteterskel krever Owner- eller Service-rollen.\n\nFor å aktivere disse kontrollene, gi Owner- eller Service-tilgang for denne installasjonen til denne kontoen i Zaptec Portal."
+        }
     }
 }

custom_components/zaptec/translations/nl.json

@@ -192,5 +192,11 @@
                 "name": "Firmware"
             }
         }
+    },
+    "issues": {
+        "insufficient_role": {
+            "title": "Beperkte toegang tot {installation_name}",
+            "description": "Het Zaptec-account dat door deze integratie wordt gebruikt heeft alleen de volgende rol(len) op installatie \"{installation_name}\": {role}. Het wijzigen van de beschikbare stroom of de 3-naar-1-fase omschakeldrempel vereist de rol Owner of Service.\n\nOm deze bedieningselementen in te schakelen, geef Owner- of Service-toegang voor deze installatie aan dit account in het Zaptec Portal."
+        }
     }
 }

custom_components/zaptec/translations/nn.json

@@ -192,5 +192,11 @@
                 "name": "Fastvareoppdatering"
             }
         }
+    },
+    "issues": {
+        "insufficient_role": {
+            "title": "Avgrensa tilgang til {installation_name}",
+            "description": "Zaptec-kontoen som blir brukt av denne integrasjonen har berre følgjande rolle(r) på installasjonen «{installation_name}»: {role}. Å endre tilgjengeleg straum eller 3-til-1-fase bytteterskel krev Owner- eller Service-rolla.\n\nFor å aktivere desse kontrollane, gi Owner- eller Service-tilgang for denne installasjonen til denne kontoen i Zaptec Portal."
+        }
     }
 }

custom_components/zaptec/translations/pl.json

@@ -192,5 +192,11 @@
                 "name": "Aktualizacja oprogramowania"
             }
         }
+    },
+    "issues": {
+        "insufficient_role": {
+            "title": "Ograniczony dostęp do {installation_name}",
+            "description": "Konto Zaptec używane przez tę integrację ma tylko następującą rolę (role) w instalacji „{installation_name}”: {role}. Zmiana dostępnego prądu lub progu przełączania 3-fazowego na 1-fazowe wymaga roli Owner lub Service.\n\nAby włączyć te funkcje, nadaj temu kontu dostęp Owner lub Service dla tej instalacji w portalu Zaptec."
+        }
     }
 }

custom_components/zaptec/translations/sv.json

@@ -192,5 +192,11 @@
                 "name": "Uppdatera mjukvara"
             }
         }
+    },
+    "issues": {
+        "insufficient_role": {
+            "title": "Begränsad åtkomst till {installation_name}",
+            "description": "Zaptec-kontot som används av den här integrationen har endast följande roll(er) på installationen \"{installation_name}\": {role}. Att ändra tillgänglig ström eller 3-till-1-fas växlingströskeln kräver rollen Owner eller Service.\n\nFör att aktivera dessa kontroller, ge Owner- eller Service-åtkomst för den här installationen till det här kontot i Zaptec Portal."
+        }
     }
 }

custom_components/zaptec/zaptec/__init__.py

@@ -3,11 +3,13 @@
 from __future__ import annotations
 
 from .api import Charger, Installation, Zaptec, ZaptecBase
-from .const import MISSING, Missing
+from .const import MISSING, RETRYABLE_HTTP_STATUSES, Missing
 from .exceptions import (
     AuthenticationError,
+    InsufficientRoleError,
     RequestConnectionError,
     RequestDataError,
+    RequestError,
     RequestRetryError,
     RequestTimeoutError,
     ZaptecApiError,
@@ -18,14 +20,17 @@
 
 __all__ = [
     "MISSING",
+    "RETRYABLE_HTTP_STATUSES",
     "ZCONST",
     "AuthenticationError",
     "Charger",
     "Installation",
+    "InsufficientRoleError",
     "Missing",
     "Redactor",
     "RequestConnectionError",
     "RequestDataError",
+    "RequestError",
     "RequestRetryError",
     "RequestTimeoutError",
     "Zaptec",