Phase 4: entity translations, a useful diagnostic sensor, diagnostics

P2-1 — has_entity_name was set but each entity then hardcoded an English
_attr_name, so a Home Assistant running in another language showed
English names. The names move to strings.json under a translation key,
which is what core requires. The config and options flows were already
translated, so only the entity block was missing.

P2-2 — the status sensor reported "Connected" or "Empty", and "Empty"
was unreachable: after the first refresh coordinator.data is always a
non-empty dict, and before it the entity is unavailable anyway, so
"Connected" only restated the availability the entity already reported.

It now reports when the cellar last synchronised, which is what tells a
user that a six-hourly integration is still alive. It keeps its unique
id, so the existing entity is repurposed rather than orphaned, and no
second entity appears. Because the old value never changed once running,
nothing could have been triggering on a transition — which is what makes
the replacement safe rather than breaking. Existing installs keep the
entity id sensor.<account>_status; fresh ones get _last_synchronised.

P2-6 — its attributes were a fixed API path and a sentence of setup
advice, persisted by the recorder on every state write. The README
documents the endpoint; the state machine is not the place for docs.

P2-3 — diagnostics.py, sequenced after P0-3 deliberately: a diagnostics
download is routinely pasted into a public issue, so it is exactly the
path that would have turned that latent credential exposure into a live
one. Redacts the password and the username, and per bottle the Barcode,
Location and Bin. Keeps the column list, which is the signal behind every
"no 'iWine' column" report, plus one redacted sample row.

P2-4 — the value sensor is MONETARY with state_class TOTAL, so it keeps
a long-term statistic, and Home Assistant treats a unit change on an
existing statistic as an error. The statistic is worth keeping: cellar
value over time is the point of the sensor. So the sensor is unchanged
and the *change* is made loud instead — the options form says what will
happen beforehand, and a warning names both currencies at the moment the
user makes the change and can still act on it.

P3-4 — an unrecognised currency became USD silently, labelling a cellar
in the wrong currency. Only reachable from legacy entry data, which is
where it would least likely be noticed. It now warns and says how to fix
it. Recognised codes and mapped legacy symbols stay silent.

P3-3 — every sensor class now carries a docstring.

The SensorEntity test double now resolves public properties from their
_attr_ attributes the way Home Assistant's Entity base does, so these
tests read the same surface a real instance would rather than reaching
for private attributes.

40 tests added, 270 passing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LLPEGFSy3fLEuXNUPAPWR4

Author: claude

README.md

@@ -69,7 +69,11 @@ reach that data.
 |---|---|---|---|---|
 | Total bottles | `142` | `bottles` | — | `measurement` |
 | Total value | `9812.50` | your chosen currency | `monetary` | `total` |
-| Status | `Connected` | — | — | diagnostic |
+| Last synchronised | `2026-08-28 09:30:00` | — | `timestamp` | diagnostic |
+
+Upgrading from 0.0.17 or earlier: the diagnostic entity that reported `Connected` now reports
+when the cellar last synchronised. It keeps its entity ID, so nothing has to be repointed. Its old
+value never changed once the integration was running, so nothing could have been triggering on it.
 
 ### Entity IDs
 
@@ -78,9 +82,13 @@ The device is named after the account, so entity IDs follow the account name:
 ```
 sensor.<account>_total_bottles
 sensor.<account>_total_value
-sensor.<account>_status
+sensor.<account>_last_synchronised
 ```
 
+That third ID is what a **fresh install** gets. An install that predates 0.0.18 keeps
+`sensor.<account>_status`, because Home Assistant assigns an entity ID once, at first
+registration, and never rewrites it. Both point at the same entity; only the name differs.
+
 **If you installed before v0.0.15**, your entity IDs were generated when the entities were first
 registered and Home Assistant keeps them — they will still be `sensor.cellartracker_total_bottles`
 and friends. Existing dashboards and automations keep working; only the display names change.

custom_components/cellar_tracker/cellar_data.py

@@ -27,6 +27,7 @@
 from homeassistant.helpers.aiohttp_client import async_get_clientsession
 from homeassistant.helpers.json import json_bytes
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
+from homeassistant.util import dt as dt_util
 
 from .const import (
     CONF_CURRENCY,
@@ -228,6 +229,10 @@ def __init__(self, hass: HomeAssistant, entry: ConfigEntry):
         # one refresh runs at a time - so the loop can read it without a lock.
         self._inventory_body: bytes = b"[]"
 
+        # When the cellar last synchronised. None until the first success, so
+        # the sensor can report "unknown" rather than invent a time.
+        self._last_success = None
+
     @property
     def currency(self) -> str:
         """Return the configured currency symbol."""
@@ -245,6 +250,16 @@ def inventory_body(self) -> bytes:
         """
         return self._inventory_body
 
+    @property
+    def last_success(self):
+        """When the last poll succeeded, or None if none has yet.
+
+        ``last_update_success`` says whether the most recent attempt worked;
+        this says when the data was last actually refreshed, which is what
+        tells a user that a six-hourly integration is still alive.
+        """
+        return self._last_success
+
     def _backoff_for(self, retry_after: int | None) -> timedelta:
         """How long to wait after being throttled.
 
@@ -420,6 +435,7 @@ async def _async_update_data(self) -> dict:
             # than leaving the coordinator to log a traceback.
             raise UpdateFailed(f"Malformed CellarTracker export: {err}") from err
 
+        self._last_success = dt_util.utcnow()
         self._restore_interval()
         return data
 

custom_components/cellar_tracker/config_flow.py

@@ -130,23 +130,42 @@ class CellarTrackerOptionsFlowHandler(config_entries.OptionsFlow):
 
     # `self.config_entry` is provided automatically by the base class.
 
+    def _current_currency(self) -> str:
+        return normalize_currency(
+            self.config_entry.options.get(
+                CONF_CURRENCY, self.config_entry.data.get(CONF_CURRENCY, DEFAULT_CURRENCY)
+            )
+        )
+
     async def async_step_init(self, user_input=None):
         """Manage the options."""
         if user_input is not None:
+            previous = self._current_currency()
             user_input[CONF_CURRENCY] = normalize_currency(
                 user_input.get(CONF_CURRENCY, DEFAULT_CURRENCY)
             )
+            if user_input[CONF_CURRENCY] != previous:
+                # The cellar value is a long-term statistic, and Home Assistant
+                # treats a unit change on an existing statistic as an error: it
+                # logs a mismatch and stops recording until the statistic is
+                # cleared. Say so here, where the user has just done it and can
+                # still act, rather than leaving them to find it in the log.
+                _LOGGER.warning(
+                    "CellarTracker currency changed from %s to %s. This relabels "
+                    "the cellar value rather than converting it, and Home "
+                    "Assistant will refuse to record the value sensor's "
+                    "long-term statistic until its existing statistic is "
+                    "cleared in Developer tools > Statistics.",
+                    previous,
+                    user_input[CONF_CURRENCY],
+                )
             return self.async_create_entry(title="", data=user_input)
 
         current_scan_interval = self.config_entry.options.get(
             CONF_SCAN_INTERVAL,
             self.config_entry.data.get(CONF_SCAN_INTERVAL, DEFAULT_SCAN_INTERVAL),
         )
-        current_currency = normalize_currency(
-            self.config_entry.options.get(
-                CONF_CURRENCY, self.config_entry.data.get(CONF_CURRENCY, DEFAULT_CURRENCY)
-            )
-        )
+        current_currency = self._current_currency()
 
         options_schema = vol.Schema(
             {

custom_components/cellar_tracker/const.py

@@ -1,5 +1,9 @@
 """Constants for the CellarTracker integration."""
 
+import logging
+
+_LOGGER = logging.getLogger(__name__)
+
 DOMAIN = "cellar_tracker"
 PLATFORMS = ["sensor"]
 
@@ -73,4 +77,16 @@ def normalize_currency(value: str | None) -> str:
     if value_upper in CURRENCY_OPTIONS:
         return value_upper
 
-    return LEGACY_CURRENCY_MAP.get(value, DEFAULT_CURRENCY)
+    if value in LEGACY_CURRENCY_MAP:
+        return LEGACY_CURRENCY_MAP[value]
+
+    # Only reachable from entry data written before the flows constrained the
+    # choice - which is exactly where labelling someone's cellar in the wrong
+    # currency would go unnoticed.
+    _LOGGER.warning(
+        "Unrecognised CellarTracker currency %r; falling back to %s. Set the "
+        "currency again in the integration options to correct it.",
+        value,
+        DEFAULT_CURRENCY,
+    )
+    return DEFAULT_CURRENCY

custom_components/cellar_tracker/diagnostics.py

@@ -0,0 +1,56 @@
+"""Diagnostics for the CellarTracker integration.
+
+A diagnostics download is routinely pasted into a public issue, so the question
+is not only what would help us but what the user would regret publishing.
+
+Redacted: the password, and the username too - it is half of a credential pair
+and names a real CellarTracker account. Per bottle, the Barcode, Location and
+Bin, which describe someone's home and are no use in diagnosing a parsing bug.
+
+Kept: the column list, which is the signal that matters. Every "no 'iWine'
+column" report comes down to CellarTracker having changed its export, and the
+column names are how we see that without asking for a copy of the cellar.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from homeassistant.components.diagnostics import async_redact_data
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.const import CONF_PASSWORD, CONF_USERNAME
+from homeassistant.core import HomeAssistant
+
+TO_REDACT = {CONF_PASSWORD, CONF_USERNAME}
+
+BOTTLE_REDACT = {"Barcode", "Location", "Bin"}
+
+
+async def async_get_config_entry_diagnostics(
+    hass: HomeAssistant, entry: ConfigEntry
+) -> dict[str, Any]:
+    """Return redacted diagnostics for a config entry."""
+    coordinator = entry.runtime_data
+    data = coordinator.data or {}
+    bottles = data.get("bottles") or []
+
+    return {
+        "entry": async_redact_data(entry.as_dict(), TO_REDACT),
+        "coordinator": {
+            "last_update_success": coordinator.last_update_success,
+            "last_success": coordinator.last_success,
+            "update_interval": str(coordinator.update_interval),
+            "currency": coordinator.currency,
+        },
+        "totals": {
+            "total_bottles": data.get("total_bottles"),
+            "total_value": data.get("total_value"),
+        },
+        # Sorted so two reports can be diffed when a schema change is suspected.
+        "columns": sorted(bottles[0]) if bottles else [],
+        # One row is enough to show how the export is shaped. Shipping the whole
+        # cellar would be both useless and a privacy problem.
+        "sample_bottle": (
+            async_redact_data(bottles[0], BOTTLE_REDACT) if bottles else None
+        ),
+    }

custom_components/cellar_tracker/sensor.py

@@ -37,20 +37,23 @@ async def async_setup_entry(
     sensors = [
         TotalBottlesSensor(coordinator, device_info, entry.entry_id),
         TotalValueSensor(coordinator, device_info, entry.entry_id, currency),
-        CellarInventorySensor(coordinator, device_info, entry.entry_id),
+        CellarLastSyncSensor(coordinator, device_info, entry.entry_id),
     ]
 
     async_add_entities(sensors)
 
 
 class TotalBottlesSensor(CoordinatorEntity, SensorEntity):
+    """How many bottles the cellar currently holds."""
+
     # Home Assistant composes the friendly name as "<device> <entity>", so the
-    # entity name must not repeat the integration's own name.
+    # entity name must not repeat the integration's own name. The name itself
+    # comes from strings.json via the translation key, not from a literal here.
     _attr_has_entity_name = True
+    _attr_translation_key = "total_bottles"
 
     def __init__(self, coordinator, device_info, entry_id):
         super().__init__(coordinator)
-        self._attr_name = "Total bottles"
         self._attr_unique_id = f"{entry_id}_total_bottles"
         self._attr_icon = "mdi:bottle-wine"
         self._attr_device_info = device_info
@@ -64,11 +67,19 @@ def native_value(self):
 
 
 class TotalValueSensor(CoordinatorEntity, SensorEntity):
+    """What the cellar is worth, in the configured currency.
+
+    MONETARY with state_class TOTAL, so Home Assistant keeps a long-term
+    statistic - cellar value over time being the reason to have the sensor.
+    That also means the unit cannot change without invalidating the existing
+    statistic, which is why the options flow warns before letting it happen.
+    """
+
     _attr_has_entity_name = True
+    _attr_translation_key = "total_value"
 
     def __init__(self, coordinator, device_info, entry_id, currency=DEFAULT_CURRENCY):
         super().__init__(coordinator)
-        self._attr_name = "Total value"
         self._attr_unique_id = f"{entry_id}_total_value"
         self._attr_device_info = device_info
         self._attr_device_class = SensorDeviceClass.MONETARY
@@ -81,29 +92,35 @@ def native_value(self):
         return (self.coordinator.data or {}).get("total_value", 0.0)
 
 
-class CellarInventorySensor(CoordinatorEntity, SensorEntity):
-    """
-    Master sensor indicating status.
-    NOTE: Detailed bottle list is exposed via API, not attributes, to avoid DB crash.
+class CellarLastSyncSensor(CoordinatorEntity, SensorEntity):
+    """When the cellar last synchronised with CellarTracker.
+
+    This replaces a status sensor that reported "Connected" or "Empty". After
+    the first refresh ``coordinator.data`` is always a non-empty dict - an
+    empty cellar still yields ``{"total_bottles": 0, ...}`` - and before it the
+    entity is unavailable anyway, so "Empty" was unreachable and "Connected"
+    only restated the availability the entity already reports.
+
+    It keeps the old unique id, so the existing entity is repurposed rather
+    than orphaned and a second one is not created. Nothing could have been
+    triggering on the old value, which never changed.
+
+    A timestamp is what a user actually needs from a diagnostic entity here: it
+    is how you tell that an integration polling every six hours is still alive.
     """
+
     _attr_has_entity_name = True
+    _attr_translation_key = "last_synchronised"
 
     def __init__(self, coordinator, device_info, entry_id):
         super().__init__(coordinator)
-        self._attr_name = "Status"
         self._attr_unique_id = f"{entry_id}_inventory_status"
-        self._attr_icon = "mdi:api"
+        self._attr_icon = "mdi:cloud-check-outline"
         self._attr_device_info = device_info
+        self._attr_device_class = SensorDeviceClass.TIMESTAMP
         self._attr_entity_category = EntityCategory.DIAGNOSTIC
 
     @property
     def native_value(self):
-        return "Connected" if self.coordinator.data else "Empty"
-
-    @property
-    def extra_state_attributes(self):
-        # We purposely do NOT include 'bottles' here.
-        return {
-            "api_endpoint": "/api/cellartracker/inventory",
-            "info": "Configure Flex Table Card with 'url: /api/cellartracker/inventory'"
-        }
+        """The last successful refresh, or None if none has happened yet."""
+        return self.coordinator.last_success

custom_components/cellar_tracker/strings.json

@@ -37,7 +37,21 @@
         "data": {
           "scan_interval": "Seconds between refreshes",
           "currency": "Currency"
-        }
+        },
+        "description": "Changing the currency relabels the cellar value; it does not convert it. Home Assistant records the value as a long-term statistic in its current unit, so after a change you may need to clear that sensor's statistics before it records again."
+      }
+    }
+  },
+  "entity": {
+    "sensor": {
+      "total_bottles": {
+        "name": "Total bottles"
+      },
+      "total_value": {
+        "name": "Total value"
+      },
+      "last_synchronised": {
+        "name": "Last synchronised"
       }
     }
   }

custom_components/cellar_tracker/translations/en.json

@@ -37,7 +37,21 @@
         "data": {
           "scan_interval": "Seconds between refreshes",
           "currency": "Currency"
-        }
+        },
+        "description": "Changing the currency relabels the cellar value; it does not convert it. Home Assistant records the value as a long-term statistic in its current unit, so after a change you may need to clear that sensor's statistics before it records again."
+      }
+    }
+  },
+  "entity": {
+    "sensor": {
+      "total_bottles": {
+        "name": "Total bottles"
+      },
+      "total_value": {
+        "name": "Total value"
+      },
+      "last_synchronised": {
+        "name": "Last synchronised"
       }
     }
   }