Development (#39)

* Release v1.4.2: End-to-end release pipeline validation

- Test consolidated auto-release.yml workflow functionality
- Validate VERSION detection and changelog extraction fixes
- Confirm complete tag → release automation works properly
- Verify v1.4.1 pipeline issues have been resolved

* Chore/update dependencies (#26)

* Release v1.4.2: End-to-end release pipeline validation (#22)

- Test consolidated auto-release.yml workflow functionality
- Validate VERSION detection and changelog extraction fixes
- Confirm complete tag → release automation works properly
- Verify v1.4.1 pipeline issues have been resolved

Co-authored-by: Brian McFarlane <bmcfarlane@dataminr.com>

* fix: grant permissions for dependency workflow (#24)

* chore: update dependencies

---------

Co-authored-by: Brian McFarlane <bmcfarlane@dataminr.com>
Co-authored-by: samspade21 <samspade21@users.noreply.github.com>

* Enhance Vacasa API resiliency and add rich sensors (#25)

* refactor: streamline vacasa sensor setup (#27)

* Refactor blocking IO helpers (#28)

* Throttle API-backed Vacasa sensors to coordinator interval (#33)

* feat(sensor): Add VacasaNextStaySensor with API throttling (#32)

Implements next_stay sensor with comprehensive reservation attributes:
- Displays next upcoming or current reservation
- Provides detailed attributes: checkin/checkout dates, stay type, guest info
- Computes days_until_checkin, days_until_checkout, stay_duration_nights
- Supports guest, owner, maintenance, and block stay classifications
- Human-readable state with contextual messages

Changes:
- Added SENSOR_NEXT_STAY constant to const.py
- Added VacasaNextStaySensor class using VacasaApiUpdateMixin pattern
- Integrated sensor into UNIT_SENSOR_CLASSES tuple
- Adopts API throttling pattern from PR #33 for coordinator-synced updates

Conflict resolution:
- Resolved merge conflict in sensor.py from PR #33
- Refactored to use VacasaApiUpdateMixin for proper API throttling
- Changed async_update() to _async_update_from_api() pattern

* Use coordinator updates for statement sensor

* Fix token handling access and clean cache imports (#35)

* fix: keep occupancy sensor aligned with reservations (#37)

* refactor: Remove stay_type_mapping and API version configuration options

Simplifies integration configuration by removing custom stay type mapping and API version selection:

Removed Configuration:
- CONF_API_VERSION and CONF_STAY_TYPE_MAPPING constants
- DEFAULT_STAY_TYPE_MAP constant (redundant)
- API version and stay type mapping parameters from VacasaApiClient
- stay_type_mapping logic from categorize_reservation (now uses direct checks)
- API version and stay type mapping UI fields from config flow

Kept Functionality:
- Stay type constants (STAY_TYPE_GUEST, etc.) for categorization
- STAY_TYPE_TO_CATEGORY and STAY_TYPE_TO_NAME mappings for internal use
- API version fallback logic in api_client._request()
- Automatic stay type detection based on reservation attributes

Reasoning:
- Simplifies user configuration (fewer options to manage)
- Stay types are automatically detected from Vacasa API responses
- API version fallback provides automatic resilience
- Reduces maintenance burden of custom mapping configurations

Files Modified:
- const.py: Removed config constants and DEFAULT_STAY_TYPE_MAP
- api_client.py: Removed stay_type_mapping parameter and simplified categorization
- __init__.py: Removed configuration reading for removed options
- config_flow.py: Removed UI fields for API version and stay type mapping

* fix: Handle charset in API content-type header for JSON parsing

The Vacasa API recently started including charset in content-type headers
(e.g., 'application/json; charset=utf-8' instead of 'application/json').
The exact equality check in _request() was failing, causing the method to
return unparsed text strings instead of JSON dictionaries.

This caused 'string indices must be integers' errors at line 947 and other
locations where code expected dictionary responses like data['data'].

Changes:
- Always attempt JSON parsing when return_json=True regardless of content-type
- Catch both aiohttp.ContentTypeError and json.JSONDecodeError exceptions
- Add diagnostic logging with URL, content-type, error, and response preview
- Fall back to returning text if JSON parsing fails (preserves existing behavior)

Fixes critical integration failure preventing all Vacasa sensors, binary
sensors, and calendars from loading.

Resolves: #36

* debug: Add diagnostic logging for VacasaNextStaySensor troubleshooting

* fix: Critical bug fixes for entity registration, JSON parsing, and imports

- fix(cached_data): Add missing random import
  * Required by RetryWithBackoff.calculate_delay() for jitter calculation
  * Prevents runtime NameError when retry logic is triggered

- fix(api_client): Handle charset in API content-type headers for JSON parsing
  * API may return 'application/json; charset=utf-8' instead of plain 'application/json'
  * Added fallback JSON parsing with diagnostic logging for troubleshooting
  * Prevents ContentTypeError when parsing valid JSON responses

- fix(sensor): Prevent premature state write before entity registration
  * Added entity_id check before calling async_write_ha_state()
  * Ensures entities are fully registered before state updates
  * Fixes AttributeError when sensors refresh during initialization

All fixes tested and verified to resolve production issues.

* style: Fix linting errors for CI/CD compliance

- Fix E402: Move imports to top of file in api_client.py
- Fix E501: Break long lines to comply with 100 char limit
- Fix D107/D102: Add missing docstrings to class methods
- Improve code formatting and readability

Resolves pre-commit hook failures in GitHub Actions.

* Handle all candidate calendar entity IDs during recovery (#40)

---------

Co-authored-by: Brian McFarlane <bmcfarlane@dataminr.com>
Co-authored-by: samspade21 <samspade21@users.noreply.github.com>

Author: samspade21

custom_components/vacasa/api_client.py

@@ -14,10 +14,6 @@
 import aiohttp
 
 from .cached_data import CachedData, RetryWithBackoff
-
-T = TypeVar("T")
-
-
 from .const import (
     API_BASE_TEMPLATE,
     AUTH_URL,
@@ -45,6 +41,8 @@
     TOKEN_REFRESH_MARGIN,
 )
 
+T = TypeVar("T")
+
 _LOGGER = logging.getLogger(__name__)
 
 
@@ -354,7 +352,6 @@ async def _request(
                         self._set_api_version(version)
                         if not return_json:
                             return await response.text()
-                        
                         # Always attempt JSON parsing when return_json=True
                         # API may include charset in content-type (e.g., "application/json; charset=utf-8")
                         try:

custom_components/vacasa/binary_sensor.py

@@ -232,18 +232,22 @@ async def _find_calendar_entity_with_retry(self, max_retries: int = 3) -> str |
         )
         return None
 
-    async def _find_calendar_entity(self) -> str | None:
-        """Find the corresponding calendar entity ID for this unit."""
-        _LOGGER.debug("Searching for calendar entity for unit %s (%s)", self._unit_id, self._name)
-
-        # Generate possible entity IDs to try
+    def _candidate_calendar_entity_ids(self) -> list[str]:
+        """Return all possible calendar entity IDs for this unit."""
         sanitized_name = self._sanitize_entity_name(self._name)
-        possible_entity_ids = [
+        return [
             f"calendar.vacasa_{sanitized_name}",
             f"calendar.vacasa_calendar_{self._unit_id}",
             f"calendar.vacasa_{self._unit_id}",
         ]
 
+    async def _find_calendar_entity(self) -> str | None:
+        """Find the corresponding calendar entity ID for this unit."""
+        _LOGGER.debug("Searching for calendar entity for unit %s (%s)", self._unit_id, self._name)
+
+        # Generate possible entity IDs to try
+        possible_entity_ids = self._candidate_calendar_entity_ids()
+
         # First try: Check state registry (faster)
         for entity_id in possible_entity_ids:
             state = self.hass.states.get(entity_id)
@@ -536,13 +540,12 @@ def _handle_calendar_state_change(self, event: Event) -> None:
         event_data = event.data
         entity_id = event_data.get("entity_id", "")
 
-        # Only respond to calendar entity state changes
-        if not entity_id.startswith("calendar.vacasa_"):
-            return
+        # Only respond to calendar entity state changes we expect
+        expected_entities: set[str] = set(self._candidate_calendar_entity_ids())
+        if self._calendar_entity:
+            expected_entities.add(self._calendar_entity)
 
-        # Check if this is our expected calendar entity
-        expected_calendar_entity = f"calendar.vacasa_{self._sanitize_entity_name(self._name)}"
-        if entity_id != expected_calendar_entity:
+        if entity_id not in expected_entities:
             return
 
         new_state = event_data.get("new_state")

custom_components/vacasa/sensor.py

@@ -95,25 +95,29 @@ class VacasaApiUpdateMixin:
 
     _refresh_task: asyncio.Task[None] | None
 
-    def __init__(self, *args, **kwargs) -> None:  # noqa: ANN002,ANN003 - pass through
+    def __init__(self, *args, **kwargs) -> None:  # noqa: ANN002,ANN003
+        """Initialize API update mixin."""
         self._update_lock = asyncio.Lock()
         self._refresh_task = None
         super().__init__(*args, **kwargs)
         self._attr_should_poll = False
 
     async def async_added_to_hass(self) -> None:
+        """Register coordinator listener when added to hass."""
         await super().async_added_to_hass()
         self.async_on_remove(
             self._coordinator.async_add_listener(self._handle_coordinator_refresh)
         )
         await self.async_update()
 
     async def async_update(self) -> None:
+        """Update entity state from API."""
         task = self._ensure_refresh_task()
         if task is not None:
             await task
 
     async def async_will_remove_from_hass(self) -> None:
+        """Clean up refresh task when removed from hass."""
         if self._refresh_task and not self._refresh_task.done():
             self._refresh_task.cancel()
             with suppress(asyncio.CancelledError):
@@ -654,6 +658,7 @@ def __init__(
         name: str,
         unit_attributes: dict[str, Any],
     ) -> None:
+        """Initialize home info sensor."""
         super().__init__(
             coordinator=coordinator,
             unit_id=unit_id,
@@ -717,6 +722,7 @@ def __init__(
         unit_attributes: dict[str, Any],
         status: str = "open",
     ) -> None:
+        """Initialize maintenance sensor."""
         super().__init__(
             coordinator=coordinator,
             unit_id=unit_id,
@@ -777,6 +783,7 @@ class VacasaStatementSensor(VacasaApiUpdateMixin, SensorEntity):
     """Sensor exposing the latest owner statement totals."""
 
     def __init__(self, coordinator, config_entry: VacasaConfigEntry) -> None:
+        """Initialize statement sensor."""
         super().__init__()
         self._coordinator = coordinator
         self._config_entry = config_entry
@@ -895,7 +902,9 @@ async def _async_update_from_api(self) -> None:
         try:
             # Get reservations starting from today
             today = datetime.now().strftime("%Y-%m-%d")
-            future_date = (datetime.now() + timedelta(days=365)).strftime("%Y-%m-%d")
+            future_date = (datetime.now() + timedelta(days=365)).strftime(
+                "%Y-%m-%d"
+            )
 
             _LOGGER.debug("Fetching reservations for %s from %s to %s", self._unit_id, today, future_date)
             reservations = await self._coordinator.client.get_reservations(
@@ -911,10 +920,17 @@ async def _async_update_from_api(self) -> None:
             _LOGGER.debug("Next stay for %s: %s", self._unit_id, "found" if self._reservation else "none")
 
         except (AuthenticationError, ApiError) as err:
-            _LOGGER.warning("Unable to update next stay for %s: %s", self._name, err)
+            _LOGGER.warning(
+                "Unable to update next stay for %s: %s", self._name, err
+            )
             self._reservation = None
         except Exception as err:
-            _LOGGER.error("Unexpected error updating next stay for %s: %s", self._name, err, exc_info=True)
+            _LOGGER.error(
+                "Unexpected error updating next stay for %s: %s",
+                self._name,
+                err,
+                exc_info=True,
+            )
             self._reservation = None
 
     def _find_next_stay(self, reservations: list[dict]) -> dict | None: