From 8c02a009dc39128c22d7bda33f801676bdb984f0 Mon Sep 17 00:00:00 2001
From: Tobias Gesellchen <tobias@gesellix.de>
Date: Sun, 15 Feb 2026 16:50:35 +0100
Subject: [PATCH] Update documentation for interaction session management

---
 README.md                         |  2 ++
 docs/guides/SOUNDTOUCH-SERVICE.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/README.md b/README.md
index f359d82..0413138 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@ A comprehensive solution for controlling and preserving Bose SoundTouch devices,
 - 🔧 **Service Migration**: Migrate devices to use local services instead of Bose cloud
 - 📊 **Traffic Analysis**: Proxy and log device communications
 - 📝 **HTTP Recording**: Persist interactions as re-playable `.http` files
+- 🧹 **Session Management**: Manage and cleanup recorded interaction sessions
 - 🔒 **Production Ready**: Extensive testing with real SoundTouch hardware
 - 🌐 **Cross-Platform**: Windows, macOS, Linux support
 
@@ -74,6 +75,7 @@ The `soundtouch-service` is a local server that emulates Bose's cloud services.
 - **🌐 Web Management UI**: Easy browser-based setup and management
 - **💾 Persistent Data**: Store presets, recents, and sources locally
 - **📝 HTTP Recording**: Persist all interactions as re-playable `.http` files
+- **🧹 Session Management**: Manage and cleanup recorded interaction sessions
 
 #### Quick Start:
 ```bash
diff --git a/docs/guides/SOUNDTOUCH-SERVICE.md b/docs/guides/SOUNDTOUCH-SERVICE.md
index 88a3997..5182c1c 100644
--- a/docs/guides/SOUNDTOUCH-SERVICE.md
+++ b/docs/guides/SOUNDTOUCH-SERVICE.md
@@ -375,6 +375,13 @@ The web management interface provides a comprehensive dashboard for managing you
 - **Statistics Dashboard**: Usage and error analytics
 - **Debug Tools**: Device communication testing utilities
 
+#### Interactions & Traffic Analysis
+- **Traffic Overview**: View aggregate request counts for self-handled and proxied traffic.
+- **Session Browsing**: Browse recorded interactions grouped by session.
+- **Advanced Filtering**: Filter interactions by session, category (Self/Upstream), and timestamp.
+- **Interaction Viewer**: View raw `.http` recording content directly in the browser.
+- **Session Management**: Delete individual sessions or perform bulk cleanup to keep only recent sessions.
+
 ### Usage Tips
 
 1. **First Time Setup**: The interface will guide you through initial device discovery
@@ -393,6 +400,7 @@ The service automatically records all HTTP interactions (both those handled loca
 - **Path-Based Structure**: Recordings are organized into subdirectories based on their URL path for better discoverability.
 - **Automatic Sanitization**: Variable path segments like IP addresses, Device IDs, and Account IDs are automatically identified and replaced with placeholders (e.g., `{{ip}}`, `{{deviceId}}`). The original values are preserved as comments at the top of the recorded `.http` files for easy identification.
 - **Re-playability**: An `http-client.env.json` file is generated for each session, allowing you to re-play the recorded requests immediately in IntelliJ IDEA.
+- **Management UI**: The **5. Interactions** tab provides a built-in viewer and management tools for all recorded data.
 
 ### Configuration
 
@@ -531,6 +539,26 @@ find data/stats/ -name "*.json" -mtime +90 -delete
 - `POST /setup/migrate/{deviceIP}`: Migrate a device using the specified method (XML/Hosts).
 - `GET /setup/ca.crt`: Download the Root CA certificate for manual installation.
 
+#### `GET /setup/interactions`
+Lists recorded interactions with optional filtering.
+
+**Query Parameters:**
+- `session`: Filter by session ID (optional)
+- `category`: Filter by category (`self` or `upstream`) (optional)
+- `since`: Filter by timestamp (e.g., `2026-02-15 15:00:00`) (optional)
+
+#### `GET /setup/interaction-stats`
+Returns aggregate statistics about recorded interactions across all sessions.
+
+#### `GET /setup/interaction-content?file={path}`
+Returns the raw content of a specific recorded `.http` file.
+
+#### `DELETE /setup/interactions/sessions/{sessionID}`
+Deletes all recordings associated with a specific session.
+
+#### `DELETE /setup/interactions/sessions?keep={N}`
+Bulk cleanup: deletes all but the most recent `N` sessions.
+
 ### Emulated Services
 - `/bmx/registry/v1/services`: BMX service registry.
 - `/bmx/tunein/v1/*`: TuneIn radio emulation.