From 02be18c19c6689fe5d34663dc96f8699999e37ad Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Sat, 6 Jun 2026 15:12:47 +0200 Subject: [PATCH] docs(api): reconcile stale endpoint-coverage docs against pkg/client (refs #451) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The device-API coverage docs had drifted from the code. Verified each claim against pkg/client and corrected: - UNIMPLEMENTED-ENDPOINTS.md: re-marked endpoints now implemented but still listed as candidates — setMusicServiceAccount / removeMusicServiceAccount and the stereo-pair group set (getGroup/addGroup/removeGroup/updateGroup); added a reconciliation note and clarified this tracks the speaker :8090 API, not the service router. - SUPPORTED-URLS.md: fixed the "Not Yet Implemented" lists (music services, presets, stations, navigate, speaker, requestToken/notification/playNotification are all implemented), the contradictory storePreset double-listing, the native group section, and the System Info over-claim (trackInfo non-functional, bluetoothInfo not implemented). - API-COVERAGE.md: fixed the exec-summary count (18/19 -> 20/21) to match its own table and refreshed the date. Also sanitised a real device ID (08DF1F0BA325 -> placeholder) found in SUPPORTED-URLS.md, per the repo's no-real-MACs rule. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/content/docs/analysis/API-COVERAGE.md | 6 +- docs/content/docs/analysis/SUPPORTED-URLS.md | 67 +++++++++++-------- .../docs/appendix/UNIMPLEMENTED-ENDPOINTS.md | 55 ++++++++++----- 3 files changed, 83 insertions(+), 45 deletions(-) diff --git a/docs/content/docs/analysis/API-COVERAGE.md b/docs/content/docs/analysis/API-COVERAGE.md index 7a4674e..3d86da5 100644 --- a/docs/content/docs/analysis/API-COVERAGE.md +++ b/docs/content/docs/analysis/API-COVERAGE.md @@ -1,13 +1,13 @@ --- title: "Bose SoundTouch API Coverage Analysis" --- -**Last Updated:** February 2026 +**Last Updated:** June 2026 (reconciled against `pkg/client`) **API Version:** Official Bose SoundTouch Web API v1.0 -**Implementation Status:** 100% Official Coverage + Extended Features +**Implementation Status:** Official coverage 20/21 + extended features ## Executive Summary -This Go implementation provides **complete coverage** of the Bose SoundTouch Web API with **100% of official endpoints implemented** (18/19) plus **5 additional extended features** not documented in the official API v1.0 but working with real hardware. +This Go implementation provides near-complete coverage of the Bose SoundTouch Web API with **20 of 21 official endpoints implemented** (the one exception, `/trackInfo`, is documented but non-functional on real hardware) plus **5 additional extended features** not documented in the official API v1.0 but working with real hardware. ### Key Findings - ✅ **All essential user functionality implemented** diff --git a/docs/content/docs/analysis/SUPPORTED-URLS.md b/docs/content/docs/analysis/SUPPORTED-URLS.md index 4e23c56..221ff3c 100644 --- a/docs/content/docs/analysis/SUPPORTED-URLS.md +++ b/docs/content/docs/analysis/SUPPORTED-URLS.md @@ -3,10 +3,23 @@ title: "SoundTouch supportedURLs Endpoint Analysis" --- This document provides a comprehensive analysis of the `/supportedURLs` endpoint response from real Bose SoundTouch devices and compares it with our current implementation. +> **Reconciliation note (June 2026).** The categorised lists below had drifted +> from `pkg/client`. Verified against the code, these are **implemented** and have +> been re-marked (some were wrongly under "Not Yet Implemented", and a few were +> listed twice): the music-service set (`setMusicServiceAccount`, +> `setMusicServiceOAuthAccount`, `removeMusicServiceAccount`, `serviceAvailability`), +> presets (`storePreset`, `removePreset`), stations (`searchStation`, `addStation`, +> `removeStation`), `navigate`, the native stereo-pair group set (`getGroup`, +> `addGroup`, `removeGroup`, `updateGroup`), `speaker`, `playNotification`, +> `requestToken`, `notification`. Still **not** implemented (confirmed absent from +> `pkg/client`): `search`, `standby`, `powerManagement`, `lowPowerStandby`, +> `language`, `listMediaServers`, `bluetoothInfo`, `userPlayControl`, and the +> wireless / bluetooth-pairing / software-update / source-shortcut families. + ## Discovery Summary **Test Devices:** -- Device 1: `192.0.2.11:8090` (deviceID: `08DF1F0BA325`) +- Device 1: `192.0.2.11:8090` (deviceID: `AABBCCDDEE01`) - Device 2: `192.0.2.10:8090` (deviceID: `AABBCCDDEEFF`) **Key Findings:** @@ -61,18 +74,18 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint - `/audioproducttonecontrols` - Advanced tone controls (capability-dependent) - `/audioproductlevelcontrols` - Speaker level controls (capability-dependent) -**System Info (3/3):** -- `/trackInfo` - Track information -- `/bluetoothInfo` - Bluetooth information -- `/recents` - Recently played content +**System Info (1/3):** +- `/recents` - Recently played content ✅ +- `/trackInfo` - Track information ❌ non-functional on real devices (use `/now_playing`) +- `/bluetoothInfo` - Bluetooth information ❌ not implemented in `pkg/client` -### 🔶 Partially Implemented/Different Approach +### ✅ Stereo-Pair Group Management (native) -**Zone Management:** -- `/addGroup` ⚠️ - We use `/setZone` for group management -- `/removeGroup` ⚠️ - We use `/setZone` for group management -- `/getGroup` ⚠️ - We use `/getZone` for group information -- `/updateGroup` ⚠️ - We use `/setZone` for group updates +Implemented natively in `pkg/client` (in addition to the `/setZone` multiroom path): +- `/addGroup` ✅ - `AddGroup()` +- `/removeGroup` ✅ - `RemoveGroup()` +- `/getGroup` ✅ - `GetGroup()` +- `/updateGroup` ✅ - `UpdateGroup()` ### ❌ Not Yet Implemented (High Priority) @@ -91,22 +104,22 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint - `/selectLastSoundTouchSource` - Select last SoundTouch source - `/selectLocalSource` - Select local source -**Music Services Integration:** -- `/setMusicServiceAccount` - Configure music service account -- `/setMusicServiceOAuthAccount` - OAuth account setup -- `/removeMusicServiceAccount` - Remove music service account -- `/serviceAvailability` - Check service availability +**Music Services Integration:** ✅ implemented (moved out of this list) +- ~~`/setMusicServiceAccount`~~ ✅ `SetMusicServiceAccount()` +- ~~`/setMusicServiceOAuthAccount`~~ ✅ `SetMusicServiceOAuthAccount()` +- ~~`/removeMusicServiceAccount`~~ ✅ `RemoveMusicServiceAccount()` +- ~~`/serviceAvailability`~~ ✅ `GetServiceAvailability()` **Enhanced Presets:** -- `/storePreset` - Store new preset -- `/removePreset` - Remove existing preset +- ~~`/storePreset`~~ ✅ `StorePreset()` (also listed under Fully Implemented) +- ~~`/removePreset`~~ ✅ `RemovePreset()` - `/bookmark` - Bookmark current content - `/userRating` - User rating for content **Station/Radio Management:** -- `/searchStation` - Search for stations -- `/addStation` - Add station to favorites -- `/removeStation` - Remove station from favorites +- ~~`/searchStation`~~ ✅ `SearchStation()` +- ~~`/addStation`~~ ✅ `AddStation()` +- ~~`/removeStation`~~ ✅ `RemoveStation()` - `/genreStations` - Browse stations by genre - `/stationInfo` - Station information @@ -119,7 +132,7 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint - `/systemtimeout` - System timeout settings - `/powersaving` - Power saving configuration - `/language` - Language settings -- `/speaker` - Speaker configuration +- ~~`/speaker`~~ ✅ `PlayTTS()` / `PlayURL()` (TTS & URL notifications; not "speaker configuration") **Network & Connectivity:** - `/performWirelessSiteSurvey` - WiFi site survey @@ -133,7 +146,7 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint **Content Discovery:** - `/search` - Content search -- `/navigate` - Content navigation +- ~~`/navigate`~~ ✅ `Navigate()` - `/listMediaServers` - List available media servers ### ❌ Not Yet Implemented (Low Priority) @@ -156,9 +169,9 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint **System Utilities:** - `/userActivity` - User activity tracking -- `/requestToken` - Token management -- `/notification` - Notification management -- `/playNotification` - Play notification sound +- ~~`/requestToken`~~ ✅ `RequestToken()` +- ~~`/notification`~~ ✅ `NotifySourcesUpdated()` +- ~~`/playNotification`~~ ✅ `PlayNotification()` - `/introspect` - System introspection - `/test` - System test interface @@ -229,7 +242,7 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint **Example Response Structure:** ```xml - + diff --git a/docs/content/docs/appendix/UNIMPLEMENTED-ENDPOINTS.md b/docs/content/docs/appendix/UNIMPLEMENTED-ENDPOINTS.md index 847e1ff..5aced22 100644 --- a/docs/content/docs/appendix/UNIMPLEMENTED-ENDPOINTS.md +++ b/docs/content/docs/appendix/UNIMPLEMENTED-ENDPOINTS.md @@ -3,13 +3,30 @@ title: "Unimplemented SoundTouch API Endpoints" sidebar: exclude: true --- -**Last Updated:** January 2026 +**Last Updated:** June 2026 (reconciled against `pkg/client`) **Source:** [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API) -**Current Implementation:** 35 endpoints (including preset & navigation management discovered via SoundTouch Plus Wiki) +**Current Implementation:** ~41 endpoints in `pkg/client` (see reconciliation note) **Wiki Documentation:** 87 endpoints -**Implementation Gap:** 52 endpoints +**Implementation Gap:** ~46 endpoints -This document provides comprehensive information about SoundTouch API endpoints documented in the community wiki but not yet implemented in this Go library. All examples are based on real device responses and extensive community testing. +This document covers SoundTouch **device** WebServices API endpoints (the +speaker's local `:8090` API consumed by `pkg/client`) documented in the community +wiki but not yet implemented. It is **not** about the cloud-service router +(`cmd/soundtouch-service`); for that surface see the contract checklist +`tests/integration/http-client/COVERAGE.md`. Examples are based on real device +responses and community testing. + +> **Reconciliation note (June 2026).** Verified against `pkg/client`. Since the +> last update these are **now implemented** and have been re-marked below: +> `setMusicServiceAccount` / `removeMusicServiceAccount` (`SetMusicServiceAccount`, +> `RemoveMusicServiceAccount`) and the full stereo-pair group set +> `getGroup` / `addGroup` / `removeGroup` / `updateGroup` +> (`GetGroup`, `AddGroup`, `RemoveGroup`, `UpdateGroup`). The priority-matrix +> counts further down are historical and have not all been recomputed; trust the +> per-endpoint ✅ markers over the section totals. Endpoints still listed as +> candidates (e.g. `/search`, `/standby`, `/powerManagement`, `/bluetoothInfo`, +> `/language`, `/listMediaServers`) were confirmed absent from `pkg/client` +> (some appear only in test fixtures). --- @@ -69,12 +86,15 @@ Specialized hardware-specific features. - CLI command: `preset select --slot <1-6>` - Alternative: Direct key commands (`SendKey("PRESET_1")` etc.) -### Music Service Management +### ~~Music Service Management~~ ✅ **IMPLEMENTED** Critical for streaming service integration. -#### POST /setMusicServiceAccount 🔥 **CRITICAL** +#### ~~POST /setMusicServiceAccount~~ ✅ **IMPLEMENTED** Adds a music service account to the sources list. +**Status:** **COMPLETE** - `pkg/client` exposes `SetMusicServiceAccount(...)` +(and `SetMusicServiceOAuthAccount(...)` for OAuth sources like Spotify/Amazon). + **Request Examples:** Pandora Service: @@ -111,9 +131,11 @@ NAS Music Library: - Note the `/0` suffix for STORED_MUSIC user names - Spotify requires PREMIUM account for most operations -#### POST /removeMusicServiceAccount 🔥 **CRITICAL** +#### ~~POST /removeMusicServiceAccount~~ ✅ **IMPLEMENTED** Removes an existing music service account. +**Status:** **COMPLETE** - `pkg/client` exposes `RemoveMusicServiceAccount(...)`. + **Request Examples:** Remove Pandora: @@ -630,9 +652,12 @@ Selects LOCAL source (only way to select LOCAL on some devices). /selectLocalSource ``` -### Group Management (ST-10 Stereo Pairs Only) +### ~~Group Management (ST-10 Stereo Pairs Only)~~ ✅ **IMPLEMENTED** -#### GET /getGroup 📊 **MEDIUM** +**Status:** **COMPLETE** - the full stereo-pair set is implemented in `pkg/client`: +`GetGroup()`, `AddGroup()`, `RemoveGroup()`, `UpdateGroup()`. + +#### ~~GET /getGroup~~ ✅ **IMPLEMENTED** Gets current stereo pair configuration. **Response Example (paired):** @@ -662,7 +687,7 @@ Gets current stereo pair configuration. ``` -#### POST /addGroup 📊 **MEDIUM** +#### ~~POST /addGroup~~ ✅ **IMPLEMENTED** Creates new stereo pair group. **Request Example:** @@ -688,7 +713,7 @@ Creates new stereo pair group. **Response:** Same as GET /getGroup **WebSocket Event:** `groupUpdated` sent to both devices -#### GET /removeGroup 📊 **MEDIUM** +#### ~~GET /removeGroup~~ ✅ **IMPLEMENTED** Removes existing stereo pair group. **Response:** @@ -698,7 +723,7 @@ Removes existing stereo pair group. **WebSocket Event:** `groupUpdated` sent to both devices -#### POST /updateGroup 📊 **MEDIUM** +#### ~~POST /updateGroup~~ ✅ **IMPLEMENTED** Updates stereo pair group name. **Request Example:** @@ -982,8 +1007,8 @@ func TestDeviceCompatibility(t *testing.T) { ### Phase 1: Essential Features (4 weeks) 1. ✅ **Preset Management**: ~~`storePreset`, `removePreset`, `selectPreset`~~ (IMPLEMENTED) -2. **Music Services**: `setMusicServiceAccount`, `removeMusicServiceAccount` -3. ✅ **Content Discovery**: ~~`navigate`, `search`~~ (IMPLEMENTED), `recents` +2. ✅ **Music Services**: ~~`setMusicServiceAccount`, `removeMusicServiceAccount`~~ (IMPLEMENTED) +3. ✅ **Content Discovery**: ~~`navigate`~~ (IMPLEMENTED), `search`, `recents` 4. ✅ **Station Management**: ~~`searchStation`, `addStation`, `removeStation`~~ (IMPLEMENTED) 5. **Enhanced Controls**: `userPlayControl`, `userRating` @@ -996,7 +1021,7 @@ func TestDeviceCompatibility(t *testing.T) { ### Phase 3: Advanced Features (3 weeks) 1. **Bluetooth**: `enterBluetoothPairing`, `clearBluetoothPaired` 2. **Software Updates**: `swUpdateCheck`, `swUpdateQuery` -3. **Stereo Pairs**: `getGroup`, `addGroup`, `removeGroup`, `updateGroup` +3. ✅ **Stereo Pairs**: ~~`getGroup`, `addGroup`, `removeGroup`, `updateGroup`~~ (IMPLEMENTED) 4. **Source Shortcuts**: `selectLastSource`, `selectLastSoundTouchSource` ### Phase 4: Specialized Features (2 weeks)