feat: add channel-attribution client headers

Send X-Client-Name, X-Client-Version, and X-Client-OS on every API
request (submit, result polling, and media upload ticket) so the
api-server trace middleware can attribute traffic to its originating
channel, matching the convention used by wavespeed-desktop.

- X-Client-Name defaults to "wavespeed-java"; configurable via the new
  Client.setClientName() fluent setter, with the WAVESPEED_CLIENT_NAME
  environment variable taking precedence over both.
- X-Client-Version comes from Version.VERSION (bumped to 0.2.3 along
  with pom.xml, per VERSIONING.md).
- X-Client-OS maps System.getProperty("os.name") to the shared
  lowercase vocabulary (mac -> darwin, windows, linux).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LJJXU9zyoDSBjApcUpteDt

Author: chengzeyi

pom.xml

@@ -5,7 +5,7 @@
     <artifactId>wavespeed-java-sdk</artifactId>
     <packaging>jar</packaging>
     <name>wavespeed-java-sdk</name>
-    <version>0.2.2</version>
+    <version>0.2.3</version>
     <url>https://github.com/WaveSpeedAI/wavespeed-java</url>
     <description>WaveSpeedAI Java SDK - Official Java SDK for WaveSpeedAI inference platform</description>
     <scm>

src/main/java/ai/wavespeed/Version.java

@@ -8,7 +8,7 @@ public final class Version {
     /**
      * The SDK version string.
      */
-    public static final String VERSION = "0.2.2";
+    public static final String VERSION = "0.2.3";
 
     private Version() {
         // Prevent instantiation

src/main/java/ai/wavespeed/api/Client.java

@@ -1,6 +1,7 @@
 package ai.wavespeed.api;
 
 import ai.wavespeed.Config;
+import ai.wavespeed.Version;
 import com.google.gson.Gson;
 import com.google.gson.reflect.TypeToken;
 import okhttp3.*;
@@ -54,6 +55,12 @@ public class Client {
     private final int maxRetries;
     private final int maxConnectionRetries;
     private final double retryInterval;
+    private String clientName;
+
+    /**
+     * Default value for the X-Client-Name channel-attribution header.
+     */
+    private static final String DEFAULT_CLIENT_NAME = "wavespeed-java";
 
     /**
      * Initialize the client.
@@ -127,6 +134,71 @@ public Client() {
         this(null, null, null, null, null, null);
     }
 
+    /**
+     * Set the client name reported in the X-Client-Name header for channel attribution.
+     *
+     * <p>The WAVESPEED_CLIENT_NAME environment variable takes precedence over this value.</p>
+     *
+     * @param clientName Client name to report
+     * @return This client, for chaining
+     */
+    public Client setClientName(String clientName) {
+        this.clientName = clientName;
+        return this;
+    }
+
+    /**
+     * Resolve the value for the X-Client-Name header.
+     *
+     * <p>Precedence: WAVESPEED_CLIENT_NAME environment variable &gt; setClientName() &gt; default.</p>
+     *
+     * @return Client name for channel attribution
+     */
+    private String resolveClientName() {
+        String envName = System.getenv("WAVESPEED_CLIENT_NAME");
+        if (envName != null && !envName.isEmpty()) {
+            return envName;
+        }
+        if (clientName != null && !clientName.isEmpty()) {
+            return clientName;
+        }
+        return DEFAULT_CLIENT_NAME;
+    }
+
+    /**
+     * Get the operating system name for the X-Client-OS header
+     * (lowercase: darwin/linux/windows).
+     *
+     * @return Normalized operating system name
+     */
+    private static String clientOs() {
+        String osName = System.getProperty("os.name", "").toLowerCase();
+        if (osName.contains("mac") || osName.contains("darwin")) {
+            return "darwin";
+        }
+        if (osName.contains("win")) {
+            return "windows";
+        }
+        if (osName.contains("nux") || osName.contains("nix")) {
+            return "linux";
+        }
+        return osName;
+    }
+
+    /**
+     * Add the channel-attribution headers (X-Client-Name, X-Client-Version,
+     * X-Client-OS) sent on every API request.
+     *
+     * @param builder Request builder to add headers to
+     * @return The same builder, for chaining
+     */
+    private Request.Builder addClientHeaders(Request.Builder builder) {
+        return builder
+                .addHeader("X-Client-Name", resolveClientName())
+                .addHeader("X-Client-Version", Version.VERSION)
+                .addHeader("X-Client-OS", clientOs());
+    }
+
     /**
      * Get request headers with authentication.
      *
@@ -142,6 +214,9 @@ private Map<String, String> getHeaders() {
         Map<String, String> headers = new HashMap<>();
         headers.put("Content-Type", "application/json");
         headers.put("Authorization", "Bearer " + apiKey);
+        headers.put("X-Client-Name", resolveClientName());
+        headers.put("X-Client-Version", Version.VERSION);
+        headers.put("X-Client-OS", clientOs());
         return headers;
     }
 
@@ -179,14 +254,14 @@ private SubmitResult submit(
 
         for (int retry = 0; retry <= maxConnectionRetries; retry++) {
             try {
-                Request request = new Request.Builder()
+                Request request = addClientHeaders(new Request.Builder()
                         .url(url)
                         .post(RequestBody.create(
                                 gson.toJson(body),
                                 MediaType.parse("application/json")
                         ))
                         .addHeader("Authorization", "Bearer " + apiKey)
-                        .addHeader("Content-Type", "application/json")
+                        .addHeader("Content-Type", "application/json"))
                         .build();
 
                 try (Response response = httpClient.newCall(request).execute()) {
@@ -260,10 +335,10 @@ private Map<String, Object> getResult(String requestId, Double timeout) {
 
         for (int retry = 0; retry <= maxConnectionRetries; retry++) {
             try {
-                Request request = new Request.Builder()
+                Request request = addClientHeaders(new Request.Builder()
                         .url(url)
                         .get()
-                        .addHeader("Authorization", "Bearer " + apiKey)
+                        .addHeader("Authorization", "Bearer " + apiKey))
                         .build();
 
                 try (Response response = httpClient.newCall(request).execute()) {
@@ -587,10 +662,10 @@ public String upload(String file, Double timeout) {
             payload.put("content_type", contentType);
         }
 
-        Request request = new Request.Builder()
+        Request request = addClientHeaders(new Request.Builder()
                 .url(this.baseUrl + "/api/v3/media/uploads")
                 .post(RequestBody.create(gson.toJson(payload), MediaType.parse("application/json")))
-                .addHeader("Authorization", "Bearer " + apiKey)
+                .addHeader("Authorization", "Bearer " + apiKey))
                 .build();
 
         try (Response response = httpClient.newCall(request).execute()) {

src/test/java/ai/wavespeed/ClientTest.java

@@ -3,6 +3,9 @@
 import ai.wavespeed.api.Client;
 import com.google.gson.Gson;
 import okhttp3.*;
+import okhttp3.mockwebserver.MockResponse;
+import okhttp3.mockwebserver.MockWebServer;
+import okhttp3.mockwebserver.RecordedRequest;
 import org.junit.jupiter.api.Test;
 import org.mockito.ArgumentCaptor;
 
@@ -198,6 +201,52 @@ void testRunNoThrowSyncModeTimeoutReturnsProcessing() {
         assertTrue(result.getDetail().getError().contains("Sync mode timed out"));
     }
 
+    @Test
+    void testAttributionHeadersSentOnSubmit() throws Exception {
+        try (MockWebServer server = new MockWebServer()) {
+            server.start();
+            server.enqueue(new MockResponse()
+                    .setResponseCode(200)
+                    .setBody("{\"data\": {\"status\": \"completed\", " +
+                            "\"id\": \"req-123\", \"outputs\": []}}"));
+
+            Client client = new Client("test-key", server.url("/").toString(), null, null, null, null);
+            client.run("wavespeed-ai/z-image/turbo", Map.of("prompt", "test"), null, null, true, null);
+
+            RecordedRequest recorded = server.takeRequest(1, java.util.concurrent.TimeUnit.SECONDS);
+            assertNotNull(recorded);
+            if (System.getenv("WAVESPEED_CLIENT_NAME") == null) {
+                assertEquals("wavespeed-java", recorded.getHeader("X-Client-Name"));
+            }
+            assertEquals(Version.VERSION, recorded.getHeader("X-Client-Version"));
+            String os = recorded.getHeader("X-Client-OS");
+            assertNotNull(os);
+            assertEquals(os.toLowerCase(), os);
+            assertTrue(List.of("darwin", "linux", "windows").contains(os));
+        }
+    }
+
+    @Test
+    void testAttributionHeadersWithCustomClientName() throws Exception {
+        try (MockWebServer server = new MockWebServer()) {
+            server.start();
+            server.enqueue(new MockResponse()
+                    .setResponseCode(200)
+                    .setBody("{\"data\": {\"status\": \"completed\", " +
+                            "\"id\": \"req-123\", \"outputs\": []}}"));
+
+            Client client = new Client("test-key", server.url("/").toString(), null, null, null, null)
+                    .setClientName("my-app");
+            client.run("wavespeed-ai/z-image/turbo", Map.of("prompt", "test"), null, null, true, null);
+
+            RecordedRequest recorded = server.takeRequest(1, java.util.concurrent.TimeUnit.SECONDS);
+            assertNotNull(recorded);
+            if (System.getenv("WAVESPEED_CLIENT_NAME") == null) {
+                assertEquals("my-app", recorded.getHeader("X-Client-Name"));
+            }
+        }
+    }
+
     // Helper methods
 
     private String getBaseUrl(Client client) {

src/test/java/ai/wavespeed/ModuleLevelApiTest.java

@@ -51,7 +51,7 @@ void testVersionAccess() {
         // Test version access
         String version = Wavespeed.version();
         assertNotNull(version);
-        assertEquals("0.2.2", version);
+        assertEquals("0.2.3", version);
     }
 
     @Test