From 0a2e91f837c22ce77ec018e2d3579a0a02d7dee6 Mon Sep 17 00:00:00 2001
From: Justin Sawyer <wordsandnumbers@gmail.com>
Date: Mon, 18 May 2026 15:43:34 -0700
Subject: [PATCH] =?UTF-8?q?docs:=20update=20README=20for=200.3.0=20?=
 =?UTF-8?q?=E2=80=94=20new=20clients,=20install=20snippet,=20base=20URL?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds usage sections for RoomClient, CurrentSongClient, and FeedbackClient,
plus the new SongClient methods (autocomplete, roulette, stats, requestSong).
Bumps the install snippet to 0.3.0 and switches the documented default base
URL to https to match the code.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 45 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 929f54a..f4450c3 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
 # vbclient
 
-Java client for the [Voice Box Karaoke](http://voiceboxpdx.com) API.
+Java client for the [Voice Box Karaoke](https://voiceboxpdx.com) API.
 
 ## Overview
 
-Voice Box Karaoke is a private-room karaoke platform (voiceboxpdx.com). `vbclient` is the Java SDK that wraps its HTTP API — searching the song catalog, managing per-room sessions and queues, posting popups, and controlling room lights. It's used by the [DJ VoxBox] Spring Boot backend.
+Voice Box Karaoke is a private-room karaoke platform (voiceboxpdx.com). `vbclient` is the Java SDK that wraps its HTTP API — searching the song catalog, managing per-room sessions and queues, posting popups, controlling room lights and audio, sending current-song commands, validating room codes, handling service calls, and collecting feedback. As of `0.3.0` it covers the full [karaoke API surface](https://vbsongs.com/api/v1/documentation/karaoke.html). It's used by the [DJ VoxBox] Spring Boot backend.
 
 ## Requirements
 
@@ -18,19 +18,19 @@ Voice Box Karaoke is a private-room karaoke platform (voiceboxpdx.com). `vbclien
 <dependency>
   <groupId>com.vpo</groupId>
   <artifactId>vbclient</artifactId>
-  <version>0.2.0-RELEASE</version>
+  <version>0.3.0</version>
 </dependency>
 ```
 
 ## Usage
 
-All three clients share the same constructor pattern. `root` overrides the API base URL (defaults to `http://voiceboxpdx.com`); `organization` is the 32-character org identifier required for every call.
+All clients share the same constructor pattern. `root` overrides the API base URL (defaults to `https://voiceboxpdx.com`); `organization` is the 32-character org identifier required for every call.
 
 ```java
 String org = "00000000000000000000000000000000"; // your 32-char org ID
 ```
 
-### SongClient — catalog, favorites, history
+### SongClient — catalog, favorites, history, stats
 
 ```java
 SongClient songs = new SongClient(null, org);
@@ -39,6 +39,11 @@ Search results = songs.findSongs(new Search("love"));
 Song song = songs.getSongById(68733);
 TagList tags = songs.tags();
 LanguageList languages = songs.languages();
+
+List<AutocompleteSuggestion> suggestions = songs.autocomplete("lov");
+List<Song> random = songs.roulette(new RouletteRequest());
+SongStats stats = songs.stats();
+songs.requestSong(new SongRequest("Beatles", "Let It Be"), session);
 ```
 
 ### SessionClient — sessions, popups, lights
@@ -65,6 +70,38 @@ queue.addSong(new PlayRequest(/* ... */));
 queue.reorder("CQFW", "0", "1");
 ```
 
+### CurrentSongClient — playback and audio controls
+
+```java
+CurrentSongClient current = new CurrentSongClient(null, org);
+
+current.pause("CQFW");
+current.resume("CQFW");
+current.skip("CQFW");
+current.restart("CQFW");
+current.setAudio("CQFW", 75, 0, null); // volume, pitch_shift, channels
+```
+
+### RoomClient — room validation and service calls
+
+```java
+RoomClient rooms = new RoomClient(null, org);
+
+Room room = rooms.getRoom("CQFW");
+ServiceCall call = rooms.getServiceCall("CQFW");
+rooms.setServiceCall(session, "CQFW", ServiceCall.STATE_REQUESTED);
+```
+
+### FeedbackClient — prompts and submissions
+
+```java
+FeedbackClient feedback = new FeedbackClient(null, org);
+
+List<FeedbackPrompt> prompts = feedback.getPrompts(session, "CQFW");
+feedback.submit(session, "CQFW", List.of(
+    new FeedbackResponse(prompts.get(0).getGuid(), 5, "great room")));
+```
+
 Room codes (e.g. `"CQFW"`) identify a karaoke room within the organization.
 
 ## Build & test
@@ -77,4 +114,6 @@ The same command runs on every push and pull request via [GitHub Actions](.githu
 
 ## Versioning
 
-`0.2.0-RELEASE` migrated the library to Spring Boot 3.2, Java 17, and JUnit 5. Prior `0.1.x` releases targeted Spring Boot 1.x / Java 7 / JUnit 4.
+- `0.3.0` brings the library to full parity with the karaoke API: adds `RoomClient`, `CurrentSongClient`, `FeedbackClient`, and new `SongClient` methods (`autocomplete`, `roulette`, `stats`, `requestSong`), plus profile/queue/search fields that the prior models didn't expose.
+- `0.2.0` migrated the library to Spring Boot 3.2, Java 17, and JUnit 5.
+- Prior `0.1.x` releases targeted Spring Boot 1.x / Java 7 / JUnit 4.