Release v1.5.0 (#41)

* 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)

* chore: prepare release v1.5.0

* fix: Resolve linting failures for PR #41

- Add missing newline at end of .env.example file
- Fix line length violations in api_client.py (lines 354, 361, 367)
- Fix line length violations in sensor.py (lines 909, 920, 1110, 1124)

All changes break long lines and comments to comply with 100-character limit.
Addresses GitHub Actions pre-commit check failures.

* fix: Use pre-commit-config-ci.yaml for CI checks

The CI workflow was using the local .pre-commit-config.yaml which has
auto-fix enabled. This caused ruff-format to modify files during CI,
making the checks fail.

Changed to use .pre-commit-config-ci.yaml which has check-only mode
for ruff-format, matching the intended CI behavior.

* fix: Apply ruff formatting to sensor.py

Removed unnecessary else clause after return statements in native_value property.
This fixes the ruff-format pre-commit check that was failing in CI.

---------

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

Author: samspade21

.env.example

@@ -18,4 +18,4 @@ HA_SERVER_USER=your_ssh_user
 # Home Assistant config directory (optional)
 # Default: /homeassistant
 # Uncomment and modify if your config directory is in a different location
-# HA_CONFIG_DIR=/homeassistant
+# HA_CONFIG_DIR=/homeassistant

.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
           pip install -r requirements.txt
 
       - name: Run pre-commit (ruff, mypy)
-        run: pre-commit run --all-files
+        run: pre-commit run --all-files --config .pre-commit-config-ci.yaml
 
       - name: Install test dependencies
         run: pip install pytest pytest-cov pytest-homeassistant-custom-component

CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2025-11-12
+
+### Added
+- **Next Stay Sensor**: New [`VacasaNextStaySensor`](custom_components/vacasa/sensor.py) for tracking upcoming and current reservations
+  - Displays next upcoming or current reservation with human-readable state messages
+  - Comprehensive attributes: check-in/check-out dates, stay type, guest information
+  - Computed values: days until check-in/check-out, stay duration nights
+  - Supports guest, owner, maintenance, and block stay classifications
+  - PR #32, #33, #34
+- **API Throttling**: Implemented sensor update throttling to respect coordinator refresh interval
+  - Prevents excessive API calls for multiple sensors
+  - All API-backed sensors now coordinate updates efficiently
+
+### Fixed
+- **Critical Entity Registration Fix**: Added entity_id validation before state writes to prevent AttributeError during initialization (PR #38)
+- **JSON Parsing Enhancement**: Handle charset in API content-type headers (`application/json; charset=utf-8`) with fallback parsing and diagnostic logging
+- **Missing Import Fix**: Added missing `random` import in [`cached_data.py`](custom_components/vacasa/cached_data.py) required for retry jitter calculations
+- **Occupancy Sensor Alignment**: Fixed occupancy sensor to stay properly aligned with reservation data (PR #37)
+- **Token Handling**: Resolved token access issues and cleaned up cache imports (PR #35)
+
+### Improved
+- **API Resilience**: Enhanced API client with better error handling, retry logic, and rich sensor support (PR #25)
+- **Blocking I/O Performance**: Refactored blocking I/O helpers for improved performance (PR #28)
+- **Sensor Setup Efficiency**: Streamlined sensor platform setup, reducing code by 99 lines (PR #27)
+- **Configuration Simplification**: Removed unused stay_type_mapping and API version configuration options
+
+### Changed
+- **Dependency Updates**: Updated project dependencies to latest versions (PR #26, #30)
+- **Code Quality**: Fixed linting errors for improved CI/CD compliance
+- **Coordinator Integration**: Statement sensor now uses coordinator updates for better consistency
+- **Diagnostic Logging**: Enhanced logging for VacasaNextStaySensor troubleshooting
+
+### Technical Improvements
+- All sensors now properly coordinate with data update coordinator
+- Enhanced error recovery and diagnostic capabilities
+- Improved code maintainability and reduced technical debt
+- Better separation of concerns in sensor architecture
+
+This release introduces the highly-requested next stay sensor feature while delivering critical bug fixes for production stability and enhanced API resilience.
+
 ## [1.4.2] - 2025-08-19
 
 ### Testing

VERSION

@@ -1 +1 @@
-1.4.2
+1.5.0

custom_components/vacasa/api_client.py

@@ -19,15 +19,14 @@
     AUTH_URL,
     DEFAULT_API_VERSION,
     DEFAULT_CACHE_TTL,
+    DEFAULT_CLIENT_ID,
     DEFAULT_CONN_TIMEOUT,
     DEFAULT_JITTER_MAX,
     DEFAULT_KEEPALIVE_TIMEOUT,
     DEFAULT_MAX_CONNECTIONS,
     DEFAULT_READ_TIMEOUT,
-    DEFAULT_CLIENT_ID,
     DEFAULT_TIMEOUT,
     MAX_RETRIES,
-    SUPPORTED_API_VERSIONS,
     PROPERTY_CACHE_FILE,
     RETRY_BACKOFF_MULTIPLIER,
     RETRY_DELAY,
@@ -37,6 +36,7 @@
     STAY_TYPE_OTHER,
     STAY_TYPE_OWNER,
     STAY_TYPE_TO_CATEGORY,
+    SUPPORTED_API_VERSIONS,
     TOKEN_CACHE_FILE,
     TOKEN_REFRESH_MARGIN,
 )
@@ -199,9 +199,7 @@ async def _retrieve_client_id(self) -> str | None:
         try:
             async with session.get(AUTH_URL, timeout=DEFAULT_TIMEOUT) as response:
                 if response.status != 200:
-                    _LOGGER.warning(
-                        "Failed to fetch login page for client ID: %s", response.status
-                    )
+                    _LOGGER.warning("Failed to fetch login page for client ID: %s", response.status)
                     return None
 
                 html = await response.text()
@@ -211,7 +209,7 @@ async def _retrieve_client_id(self) -> str | None:
 
         patterns = [
             r'data-client-id="([A-Za-z0-9_-]+)"',
-            r'client_id=([A-Za-z0-9_-]+)',
+            r"client_id=([A-Za-z0-9_-]+)",
         ]
 
         for pattern in patterns:
@@ -226,8 +224,7 @@ async def _ensure_client_id(self) -> str:
         """Ensure the OAuth client ID is up to date."""
         now = time.time()
         cache_valid = (
-            self._client_id_last_fetch is not None
-            and now - self._client_id_last_fetch < 3600
+            self._client_id_last_fetch is not None and now - self._client_id_last_fetch < 3600
         )
 
         if cache_valid and self._client_id:
@@ -287,7 +284,6 @@ async def ensure_session(self) -> aiohttp.ClientSession:
 
     async def _run_blocking_io(self, func: Callable[..., T], *args, **kwargs) -> T:
         """Execute a blocking IO function safely in the event loop."""
-
         if self._hass:
             return await self._hass.async_add_executor_job(func, *args, **kwargs)
         return func(*args, **kwargs)
@@ -333,7 +329,6 @@ async def _request(
         retry_on_unauthorized: bool = True,
     ) -> Any:
         """Perform an HTTP request with API version fallback and error handling."""
-
         session = await self.ensure_session()
         last_error: Exception | None = None
 
@@ -353,27 +348,27 @@ async def _request(
                         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")
+                        # API may include charset in content-type
+                        # (e.g., "application/json; charset=utf-8")
                         try:
                             return await response.json()
                         except (aiohttp.ContentTypeError, json.JSONDecodeError) as e:
                             # Log diagnostic info for troubleshooting
                             response_text = await response.text()
                             _LOGGER.warning(
-                                "Failed to parse JSON response from %s (content-type: %s): %s. Response: %s",
+                                "Failed to parse JSON from %s (content-type: %s): %s. Response: %s",
                                 url,
                                 response.content_type,
                                 e,
                                 response_text[:200],
                             )
-                            # Return text as fallback, but this will likely cause errors in calling code
+                            # Return text as fallback, but this will likely
+                            # cause errors in calling code
                             return response_text
 
                     if response.status == 401:
                         # Attempt token refresh once when unauthorized
-                        _LOGGER.warning(
-                            "API request unauthorized for %s, refreshing token", url
-                        )
+                        _LOGGER.warning("API request unauthorized for %s, refreshing token", url)
                         if retry_on_unauthorized:
                             await self.authenticate()
                             await self._save_token_to_cache()
@@ -1116,7 +1111,6 @@ async def _fetch_unit_details():
 
     async def get_home_info(self, unit_id: str) -> dict[str, Any]:
         """Return the detailed home-info payload for a unit."""
-
         await self.ensure_token()
         owner_id = await self.get_owner_id()
 
@@ -1131,7 +1125,6 @@ async def get_statements(
         self, year: int | None = None, month: int | None = None
     ) -> list[dict[str, Any]]:
         """Fetch owner statements, optionally scoped to a specific month."""
-
         await self.ensure_token()
         owner_id = await self.get_owner_id()
 
@@ -1153,7 +1146,6 @@ async def get_maintenance(
         self, unit_id: str, status: str | None = "open"
     ) -> list[dict[str, Any]]:
         """Fetch maintenance tickets for a unit."""
-
         await self.ensure_token()
         owner_id = await self.get_owner_id()
 

custom_components/vacasa/binary_sensor.py

@@ -336,9 +336,7 @@ async def _update_current_and_next_events(self) -> None:
 
             # Check if there's a current event
             if calendar_state.state == "on":
-                current_event = self._create_event_from_attributes(
-                    message, start_attr, end_attr
-                )
+                current_event = self._create_event_from_attributes(message, start_attr, end_attr)
 
                 if current_event:
                     self._current_event = current_event
@@ -355,9 +353,7 @@ async def _update_current_and_next_events(self) -> None:
                         self._name,
                     )
             else:
-                next_event = self._create_event_from_attributes(
-                    message, start_attr, end_attr
-                )
+                next_event = self._create_event_from_attributes(message, start_attr, end_attr)
 
                 if next_event:
                     self._next_event = next_event
@@ -372,10 +368,8 @@ async def _update_current_and_next_events(self) -> None:
             next_event_attr = calendar_state.attributes.get("next_event")
             if isinstance(next_event_attr, dict):
                 alt_next_event = self._create_event_from_attributes(
-                    next_event_attr.get("summary")
-                    or next_event_attr.get("message", ""),
-                    next_event_attr.get("start")
-                    or next_event_attr.get("start_time"),
+                    next_event_attr.get("summary") or next_event_attr.get("message", ""),
+                    next_event_attr.get("start") or next_event_attr.get("start_time"),
                     next_event_attr.get("end") or next_event_attr.get("end_time"),
                 )
 
@@ -598,16 +592,8 @@ def _create_event_from_attributes(
             return None
 
         try:
-            start_dt = (
-                dt_util.parse_datetime(start)
-                if isinstance(start, str)
-                else start
-            )
-            end_dt = (
-                dt_util.parse_datetime(end)
-                if isinstance(end, str)
-                else end
-            )
+            start_dt = dt_util.parse_datetime(start) if isinstance(start, str) else start
+            end_dt = dt_util.parse_datetime(end) if isinstance(end, str) else end
 
             if not start_dt or not end_dt:
                 return None

custom_components/vacasa/cached_data.py

@@ -151,7 +151,6 @@ async def cleanup_expired(self) -> int:
 
     async def _run_io_task(self, func: Callable[..., T], *args, **kwargs) -> T:
         """Execute a blocking IO task safely when hass is available."""
-
         if self._hass:
             return await self._hass.async_add_executor_job(func, *args, **kwargs)
         return func(*args, **kwargs)

custom_components/vacasa/config_flow.py

@@ -1,6 +1,5 @@
 """Config flow for Vacasa integration."""
 
-import json
 import logging
 import re
 from typing import Any, Dict, Optional

custom_components/vacasa/manifest.json

@@ -8,5 +8,5 @@
   "iot_class": "cloud_polling",
   "issue_tracker": "https://github.com/samspade21/vacasa-ha/issues",
   "requirements": ["aiohttp>=3.8.0"],
-  "version": "1.4.2"
+  "version": "1.5.0"
 }