v1.3.0-beta.6 - Migration to a dedicated asynchronous API client package

Level 3-beta.6 - Migration to a dedicated asynchronous API client package

Update

• Includes changes from v1.2.x

Changed

• Architectural Rewrite: Replaced internal API logic with the newly created, standalone bgg-pi Python package (v0.1.1). This isolates all BGG API interactions into a dedicated library.
• Service Stability: The integration now leverages bgg-pi for all network operations. This client is built from the ground up with aiohttp to be fully asynchronous and non-blocking.
• Reliability: By offloading API complexity to an external library with its own 100% test coverage, the integration core is leaner and more robust. bgg-sync itself maintains 100% coverage on the integration layer.
• Internal Cleanup: Refactored coordinator.py to use a helper method for game data mapping, strictly enforcing DRY principles and Type Hinting.

v1.2.3 - Resolve attribute reload requirement

v1.2.3 - Track Game Fix

🐛 Bug Fixes

• Track Game Updates: Fixed an issue where using the track_game service to update custom attributes (like nfc_tag, music, or custom_image) required a forced reload of the integration to take effect (#7).

---

v1.2.2 - Image Fix

🚀 New Features

• Local Image Caching: Game artwork is now automatically downloaded and cached locally on your Home Assistant instance (/config/www/bgg_images/). This serves images significantly faster and resolves issues where BGG images would occasionally fail to load or display due to hotlinking protections or whitespace errors.
• Image Optimisation: Cached images are now automatically resized to a maximum of 500x500 pixels. This drastically reduces memory usage and dashboard load times, preventing crashes when displaying large collections.
• Enhanced Custom Images: When you set a custom_image, it is now handled by the new caching system. This ensures your custom art is reliably displayed and persisted locally, correcting previous display glitches.
• Australian Localisation: Updated the record_play service to accept colour in addition to color for player details, allowing for correct Australian/British spelling.

🐛 Bug Fixes

• Fix Image Loading: Resolved an issue where BGG API responses containing whitespace would break image URLs, causing broken images in the dashboard.
• Todo List Naming: Fixed a naming bug that resulted in the Todo list entity having a duplicate name (e.g., "User's Shelf Shelf"). It now correctly displays as "User's Shelf".
• Sensor Availability: Fixed a critical bug where sensors for games tracked via service calls (but not in the BGG collection) would become "Unavailable" after a configuration update or restart.
• Attribute Persistence: Fixed an issue where custom attributes (NFC tags, Music links, Custom Images) for tracked games were lost upon integration reload.

---

v1.2.1 - Minor Improvement

Updated the device name to use just the BGG username.

---

v1.2.0 - Level 2: Players, Scores & Metadata

This beta release marks a major architectural improvement for the BGG Sync integration, migrating the core network layer to be fully asynchronous. This ensures better stability, performance, and compliance with Home Assistant's architectural standards.

🚀 Key Changes

• Last Sync Sensor: Added a diagnostic sensor (bgg_last_sync) to track the timestamp of the last successful data fetch.
• Force Sync Button: Added a diagnostic button to force a BGG sync.
• Plays Sensor Attributes: The last_play attribute is now "flattened" into top-level attributes on the Plays sensor:
  • game
  • bgg_id
  • date
  • comment (Cleaned of BBCode)
  • expansions (Extracted from comment text)
  • winners
  • players
  • image (Fetched from game metadata if available)
  • NOTE: The original nested last_play attribute dictionary has been removed.
• String Localization: Added friendly localised names for the services.
• Player Details in Recording: The record_play service now supports passing player names and winners to BoardGameGeek.

Fixed

• Clean Attribute Text: Fixed issue where BGG BBCode tags (e.g. [thing=...]) were appearing in sensor attributes (last play comments).
• Cleaned Up: Improved code comments and removed unused imports.
• Service Stability: Moved blocking legacy recording logic into an executor job to maintain Home Assistant performance standards while ensuring session persistence.

Async Migration

• Performance: Switched all network I/O from the blocking requests library to aiohttp. This prevents the integration from blocking the Home Assistant event loop during API calls, which is critical for system stability.
• Dependency Cleanup: Removed the hard dependency on requests, making the integration lighter.
• Modernisation: Updated all service calls and sensor updates to fully utilise proper async/await patterns.

🛠️ Technical Improvements

Test Suite Overhaul

• Thread Safety: Completely refactored the test suite to use isolated AsyncMock patterns for client sessions. This permanently resolves the "Lingering Thread" errors that were plaguing the test suite.
• Mocking: Removed aioclient_mock in favour of pure Python mocks for granular control over connection behaviour in tests.
• Stability: The test suite passes 100% cleanly (55 tests) with no warnings or errors.

Code Quality

• Assertions: Fixed logic assertions in configuration flow to accurately reflect error handling behaviours.

v1.2.2 - Fix Game Images

v1.2.2 - Image Fix

🚀 New Features

• Local Image Caching: Game artwork is now automatically downloaded and cached locally on your Home Assistant instance (/config/www/bgg_images/). This serves images significantly faster and resolves issues where BGG images would occasionally fail to load or display due to hotlinking protections or whitespace errors.
• Image Optimisation: Cached images are now automatically resized to a maximum of 500x500 pixels. This drastically reduces memory usage and dashboard load times, preventing crashes when displaying large collections.
• Enhanced Custom Images: When you set a custom_image, it is now handled by the new caching system. This ensures your custom art is reliably displayed and persisted locally, correcting previous display glitches.
• Australian Localisation: Updated the record_play service to accept colour in addition to color for player details, allowing for correct Australian/British spelling.

🐛 Bug Fixes

• Fix Image Loading: Resolved an issue where BGG API responses containing whitespace would break image URLs, causing broken images in the dashboard.
• Todo List Naming: Fixed a naming bug that resulted in the Todo list entity having a duplicate name (e.g., "User's Shelf Shelf"). It now correctly displays as "User's Shelf".
• Sensor Availability: Fixed a critical bug where sensors for games tracked via service calls (but not in the BGG collection) would become "Unavailable" after a configuration update or restart.
• Attribute Persistence: Fixed an issue where custom attributes (NFC tags, Music links, Custom Images) for tracked games were lost upon integration reload.

---

v1.2.1 - Minor Improvement

Updated the device name to use just the BGG username.

---

v1.2.0 - Level 2: Players, Scores & Metadata

This beta release marks a major architectural improvement for the BGG Sync integration, migrating the core network layer to be fully asynchronous. This ensures better stability, performance, and compliance with Home Assistant's architectural standards.

🚀 Key Changes

• Last Sync Sensor: Added a diagnostic sensor (bgg_last_sync) to track the timestamp of the last successful data fetch.
• Force Sync Button: Added a diagnostic button to force a BGG sync.
• Plays Sensor Attributes: The last_play attribute is now "flattened" into top-level attributes on the Plays sensor:
  • game
  • bgg_id
  • date
  • comment (Cleaned of BBCode)
  • expansions (Extracted from comment text)
  • winners
  • players
  • image (Fetched from game metadata if available)
  • NOTE: The original nested last_play attribute dictionary has been removed.
• String Localization: Added friendly localised names for the services.
• Player Details in Recording: The record_play service now supports passing player names and winners to BoardGameGeek.

Fixed

• Clean Attribute Text: Fixed issue where BGG BBCode tags (e.g. [thing=...]) were appearing in sensor attributes (last play comments).
• Cleaned Up: Improved code comments and removed unused imports.
• Service Stability: Moved blocking legacy recording logic into an executor job to maintain Home Assistant performance standards while ensuring session persistence.

Async Migration

• Performance: Switched all network I/O from the blocking requests library to aiohttp. This prevents the integration from blocking the Home Assistant event loop during API calls, which is critical for system stability.
• Dependency Cleanup: Removed the hard dependency on requests, making the integration lighter.
• Modernisation: Updated all service calls and sensor updates to fully utilise proper async/await patterns.

🛠️ Technical Improvements

Test Suite Overhaul

• Thread Safety: Completely refactored the test suite to use isolated AsyncMock patterns for client sessions. This permanently resolves the "Lingering Thread" errors that were plaguing the test suite.
• Mocking: Removed aioclient_mock in favour of pure Python mocks for granular control over connection behaviour in tests.
• Stability: The test suite passes 100% cleanly (55 tests) with no warnings or errors.

Code Quality

• Assertions: Fixed logic assertions in configuration flow to accurately reflect error handling behaviours.

v1.3.0-beta.5 - Migration to a dedicated asynchronous API client package

Level 3-beta.5 - Migration to a dedicated asynchronous API client package

Changed

• Architectural Rewrite: Replaced internal API logic with the newly created, standalone bgg-pi Python package (v0.1.1). This isolates all BGG API interactions into a dedicated library.
• Service Stability: The integration now leverages bgg-pi for all network operations. This client is built from the ground up with aiohttp to be fully asynchronous and non-blocking.
• Reliability: By offloading API complexity to an external library with its own 100% test coverage, the integration core is leaner and more robust. bgg-sync itself maintains 100% coverage on the integration layer.
• Internal Cleanup: Refactored coordinator.py to use a helper method for game data mapping, strictly enforcing DRY principles and Type Hinting.

v1.2.1 - Minor Improvement to Device name

v1.2.1 - Minor Improvement

Updated the device name to use just the BGG username.

v1.2.0 - Level 2: Players, Scores & Metadata

This beta release marks a major architectural improvement for the BGG Sync integration, migrating the core network layer to be fully asynchronous. This ensures better stability, performance, and compliance with Home Assistant's architectural standards.

🚀 Key Changes

• Last Sync Sensor: Added a diagnostic sensor (bgg_last_sync) to track the timestamp of the last successful data fetch.
• Force Sync Button: Added a diagnostic button to force a BGG sync.
• Plays Sensor Attributes: The last_play attribute is now "flattened" into top-level attributes on the Plays sensor:
  • game
  • bgg_id
  • date
  • comment (Cleaned of BBCode)
  • expansions (Extracted from comment text)
  • winners
  • players
  • image (Fetched from game metadata if available)
  • NOTE: The original nested last_play attribute dictionary has been removed.
• String Localization: Added friendly localised names for the services.
• Player Details in Recording: The record_play service now supports passing player names and winners to BoardGameGeek.

Fixed

• Clean Attribute Text: Fixed issue where BGG BBCode tags (e.g. [thing=...]) were appearing in sensor attributes (last play comments).
• Cleaned Up: Improved code comments and removed unused imports.
• Service Stability: Moved blocking legacy recording logic into an executor job to maintain Home Assistant performance standards while ensuring session persistence.

Async Migration

• Performance: Switched all network I/O from the blocking requests library to aiohttp. This prevents the integration from blocking the Home Assistant event loop during API calls, which is critical for system stability.
• Dependency Cleanup: Removed the hard dependency on requests, making the integration lighter.
• Modernisation: Updated all service calls and sensor updates to fully utilise proper async/await patterns.

🛠️ Technical Improvements

Test Suite Overhaul

• Thread Safety: Completely refactored the test suite to use isolated AsyncMock patterns for client sessions. This permanently resolves the "Lingering Thread" errors that were plaguing the test suite.
• Mocking: Removed aioclient_mock in favour of pure Python mocks for granular control over connection behaviour in tests.
• Stability: The test suite passes 100% cleanly (55 tests) with no warnings or errors.

Code Quality

• Assertions: Fixed logic assertions in configuration flow to accurately reflect error handling behaviours.

v1.2.0 - Level 2: Players, Scores & Metadata

v1.2.0 - Level 2: Players, Scores & Metadata

This beta release marks a major architectural improvement for the BGG Sync integration, migrating the core network layer to be fully asynchronous. This ensures better stability, performance, and compliance with Home Assistant's architectural standards.

🚀 Key Changes

• Last Sync Sensor: Added a diagnostic sensor (bgg_last_sync) to track the timestamp of the last successful data fetch.
• Force Sync Button: Added a diagnostic button to force a BGG sync.
• Plays Sensor Attributes: The last_play attribute is now "flattened" into top-level attributes on the Plays sensor:
  • game
  • bgg_id
  • date
  • comment (Cleaned of BBCode)
  • expansions (Extracted from comment text)
  • winners
  • players
  • image (Fetched from game metadata if available)
  • NOTE: The original nested last_play attribute dictionary has been removed.
• String Localization: Added friendly localised names for the services.
• Player Details in Recording: The record_play service now supports passing player names and winners to BoardGameGeek.

Fixed

• Clean Attribute Text: Fixed issue where BGG BBCode tags (e.g. [thing=...]) were appearing in sensor attributes (last play comments).
• Cleaned Up: Improved code comments and removed unused imports.
• Service Stability: Moved blocking legacy recording logic into an executor job to maintain Home Assistant performance standards while ensuring session persistence.

Async Migration

• Performance: Switched all network I/O from the blocking requests library to aiohttp. This prevents the integration from blocking the Home Assistant event loop during API calls, which is critical for system stability.
• Dependency Cleanup: Removed the hard dependency on requests, making the integration lighter.
• Modernisation: Updated all service calls and sensor updates to fully utilise proper async/await patterns.

🛠️ Technical Improvements

Test Suite Overhaul

• Thread Safety: Completely refactored the test suite to use isolated AsyncMock patterns for client sessions. This permanently resolves the "Lingering Thread" errors that were plaguing the test suite.
• Mocking: Removed aioclient_mock in favour of pure Python mocks for granular control over connection behaviour in tests.
• Stability: The test suite passes 100% cleanly (55 tests) with no warnings or errors.

Code Quality

• Assertions: Fixed logic assertions in configuration flow to accurately reflect error handling behaviours.

Minor Timezone Fix + Branding

Release v1.1.1

This maintenance release focuses on data accuracy, professional branding, and compliance with data attribution standards.

🌟 Key Changes

• Official Branding: The integration is now displayed as "BoardGameGeek" in the Home Assistant UI, providing a more professional and recognisable experience.
• Accurate Play Dates: The record_play service now respects your Home Assistant local time settings. Previously, plays recorded late at night (e.g., in Australian timezones) could be logged as the previous day due to UTC conversion.
• Data Attribution: Added "Data provided by BoardGameGeek" attribution to all entities, ensuring proper credit and compliance.

🛠 Full Changelog

Changed

• Branding: Updated integration name to "BoardGameGeek" in the manifest.
• Timezone Accuracy: record_play service logic updated to use homeassistant.util.dt.now() for date stamping.
• Attribution: Added _attr_attribution to all sensor and todo entities.

BGG Sync v1.1.0

BGG Sync v1.1.0

This major update introduces powerful new features for tracking your BoardGameGeek collection and significantly improves the robustness of the integration with a fully verified 100% test suite.

🌟 Highlights

🎲 Full Collection Tracking

You can now import your entire BoardGameGeek collection into Home Assistant!

• Toggle Option: Enable "Track Collection" in the configuration options to auto-create sensors for every game you own.
• Rich Metadata: Each game sensor now includes detailed data: min/max players, playtime, rank, weight, year released, and more.
• Dynamic Art: Game sensors now display the official box art as their icon/picture.

🏷️ Enhanced Game Tracking

The track_game service is smarter:

• Targeting: Add games to specific users in a multi-user setup.
• Custom Tags: Attach NFC tags or Music URIs directly when tracking a game for easier automation integration.

🛡️ Robustness & Reliability

• 100% Test Coverage: The integration has undergone a massive code quality overhaul, ensuring every line of code is tested. This means fewer bugs and higher reliability.
• API Optimization: Smarter batching of API requests prevents connection errors when syncing large collections.

📜 Changelog

Added

• Collection Tracking: New option to track your entire BGG collection as individual sensors.
• Rich Metadata Refinement: Added parsing for min_players, max_players, min_playtime, max_playtime, sub_type, year, rank, weight.
• Game Tracking Service: Enhanced bgg_sync.track_game service to support adding nfc_tag and music attributes to specific games.
• Dynamic Icons: Game sensors now display the game's box art if available, falling back to the dice icon.
• Configuration: Added "Track Collection" toggle in Options Flow.

Changed

• API Performance: Optimized batch sizing (reduced to 20) for BGG API requests to prevent "400 Bad Request" errors on large collections.
• Translations: Improved UI labels for configuration options.
• Attributes: Renamed subtype to sub_type and fixed coll_id to only appear when relevant.
• Reliability: Achieved 100% test coverage and implemented strict linting (ruff) to ensure robustness and code quality.

Fixed

• Fixed issue where game attributes (Weight, Rating, etc.) were showing as "Unknown" due to XML parsing errors.
• Fixed issue where service calls to track_game with tag or playlist aliases were ignored (now strictly nfc_tag and music).
• Fixed multi-user collection tracking support.

Bug Fixes & Improvements

🐛 Bug Fixes & Improvements

• Fixed Connection Issues: API tokens are now automatically trimmed of invisible spaces and newlines, preventing "Application Error" or "401 Unauthorized" issues caused by copying and pasting.
• Handle BGG Processing Delays: The integration now correctly handles the 202 Accepted status from BoardGameGeek.
  • Previously, this would cause a "Failed to connect" error if your collection was large or being accessed for the first time.
  • Now, setup will complete successfully, and a warning will be logged to let you know BGG is still building your collection in the background.

Full Changelog: v1.0.0...v1.0.1

Initial Release

v1.0.0 - Initial Release

BGG Sync is a robust Home Assistant integration for BoardGameGeek. It allows you to track your collection size, monitor total plays, and log new plays directly from Home Assistant.

This integration is fully updated to support BoardGameGeek's new API Token requirements.

🚀 Features

• 📊 Collection & Play Stats: Creates sensors for your total collection size and total logged plays.
• 🎲 Track Specific Games: Monitor play counts for specific games (e.g., "Carcassonne Plays") by adding their BGG IDs.
• 📝 Log Plays: A dedicated service bgg_sync.record_play allows you to log plays to your BGG account from automations or dashboards.
• ➕ Dynamic Tracking: Use the bgg_sync.track_game service to add new games to your tracking list on the fly.
• 🔐 Secure & Compliant:
  • Uses BGG API Tokens for reliable, read-only data fetching.
  • BGG Password is optional and only required if you enable the Play Logging feature.
• 👥 Multi-Account: Track data for multiple BGG users in a single Home Assistant instance.

📦 Installation

HACS (Custom Repository)

1. Open HACS in Home Assistant.
2. Click the 3 dots in the top right corner -> Custom Repositories.
3. Add the URL of this repository: https://github.com/seanmccabe/ha-bgg-sync
4. Select Category: Integration.
5. Click Add and then install "BGG Sync".
6. Restart Home Assistant.

Manual

1. Download the latest.zip from the releases page (or clone the repo).
2. Copy the custom_components/bgg_sync folder to your Home Assistant config/custom_components/ directory.
3. Restart Home Assistant.

⚙️ Configuration

1. Go to Settings > Devices & Services > Add Integration.
2. Search for BGG Sync.
3. Enter your BGG Username and API Token (Get one here: BGG API Applications).
4. (Optional) Check Enable Play Logging and enter your password if you want to record plays.

---

Full Changelog: https://github.com/seanmccabe/ha-bgg-sync/commits/v1.0.0