Implement song queue management for clients, including adding songs to preferred queue and retrieving the queue for a radio station

backend/API_DOCUMENTATION.md

@@ -23,6 +23,26 @@ Authorization: Bearer <token>
 
 #### Create Radio Station
 
+#### Get All Radio Stations
+
+#### Get Radio Station by ID
+
+#### Delete Radio Station
+
+### Client Management
+
+#### Connect Client to Station
+
+### Song Queue Management
+
+#### Add Song to Client's Preferred Queue
+
+#### Get Radio Station Queue
+
+## Radio Station Management
+
+#### Create Radio Station
+
 Creates a new radio station and returns an owner token.
 
 **Endpoint:** `POST /radio-stations`
@@ -170,6 +190,90 @@ Connects a client to a radio station using a join code. No authentication requir
 }
 ```
 
+### Song Queue Management
+
+#### Add Song to Client's Preferred Queue
+
+Adds a song to a specific client's preferred queue. The frontend can merge track and audio features objects using `const merged = { ...trackObj, ...audioFeaturesObj };`
+
+**Endpoint:** `POST /api/songs/queue`
+
+**Request Body:**
+
+```json
+{
+  "song": {
+    "id": "4iV5W9uYEdYUVa79Axb7Rh",
+    "popularity": 85,
+    "tempo": 120.5,
+    "danceability": 0.8,
+    "energy": 0.7,
+    "valence": 0.6,
+    "acousticness": 0.1,
+    "instrumentalness": 0.0,
+    "liveness": 0.1,
+    "speechiness": 0.04
+  },
+  "clientId": "client-uuid",
+  "radioStationId": "station-uuid"
+}
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "message": "Song added to client's preferred queue successfully",
+  "data": null
+}
+```
+
+#### Get Radio Station Queue
+
+Retrieves the main song queue for a radio station. Returns a list of song objects.
+
+**Endpoint:** `GET /api/songs/queue?radioStationId={radioStationId}`
+
+**Query Parameters:**
+
+- `radioStationId` (required): The ID of the radio station
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "message": "Queue retrieved successfully",
+  "data": [
+    {
+      "id": "4iV5W9uYEdYUVa79Axb7Rh",
+      "popularity": 85,
+      "tempo": 120.5,
+      "danceability": 0.8,
+      "energy": 0.7,
+      "valence": 0.6,
+      "acousticness": 0.1,
+      "instrumentalness": 0.0,
+      "liveness": 0.1,
+      "speechiness": 0.04
+    },
+    {
+      "id": "7ouMYWpwJ422jRcDASZB7P",
+      "popularity": 78,
+      "tempo": 95.0,
+      "danceability": 0.6,
+      "energy": 0.5,
+      "valence": 0.8,
+      "acousticness": 0.3,
+      "instrumentalness": 0.0,
+      "liveness": 0.2,
+      "speechiness": 0.06
+    }
+  ]
+}
+```
+
 ## Error Responses
 
 All error responses follow this format:
@@ -213,3 +317,71 @@ curl -X GET "http://localhost:8080/api/radio-stations" \
 curl -X DELETE http://localhost:8080/api/radio-stations/{stationId} \
   -H "Authorization: Bearer {ownerToken}"
 ```
+
+### Adding a Song to Client's Preferred Queue
+
+```bash
+curl -X POST http://localhost:8080/api/songs/queue \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer {clientToken}" \
+  -d '{
+    "song": {
+      "id": "4iV5W9uYEdYUVa79Axb7Rh",
+      "popularity": 85,
+      "tempo": 120.5,
+      "danceability": 0.8,
+      "energy": 0.7,
+      "valence": 0.6,
+      "acousticness": 0.1,
+      "instrumentalness": 0.0,
+      "liveness": 0.1,
+      "speechiness": 0.04
+    },
+    "clientId": "client-uuid",
+    "radioStationId": "station-uuid"
+  }'
+```
+
+### Getting Radio Station Queue
+
+```bash
+curl -X GET "http://localhost:8080/api/songs/queue?radioStationId=station-uuid" \
+  -H "Authorization: Bearer {token}"
+```
+
+## Frontend Integration Notes
+
+### Merging Track and Audio Features
+
+The frontend can easily merge track information with audio features using JavaScript object spread:
+
+```javascript
+// Track object from Spotify API
+const trackObj = {
+  id: "4iV5W9uYEdYUVa79Axb7Rh",
+  popularity: 85,
+  tempo: 120.5,
+};
+
+// Audio features object from Spotify API
+const audioFeaturesObj = {
+  danceability: 0.8,
+  energy: 0.7,
+  valence: 0.6,
+  acousticness: 0.1,
+  instrumentalness: 0.0,
+  liveness: 0.1,
+  speechiness: 0.04,
+};
+
+// Merge objects for API request
+const merged = { ...trackObj, ...audioFeaturesObj };
+```
+
+### Queue Data Structure
+
+The queue endpoints return/accept arrays of song objects. Each song object contains:
+
+- Basic track info (id, popularity, tempo)
+- Audio features (danceability, energy, valence, etc.)
+- All properties are at the root level (flattened structure)