Merge pull request #2166 from stripe/jar/merge-java-private-preview

Merge to private-preview

Author: jar-stripe

.claude/CLAUDE.md

@@ -0,0 +1,49 @@
+# stripe-java
+
+## Testing
+
+- Run all tests: `just test`
+- Run a single test class: `just test-one com.stripe.net.HttpClientTest`
+- Pass extra Gradle args: `just test --tests com.stripe.SomeTest`
+
+## Formatting
+
+- Format: `just format` (uses Spotless via Gradle)
+- Format check: `just format-check`
+
+## Key Locations
+
+- HTTP client abstract base (retry logic): `src/main/java/com/stripe/net/HttpClient.java`
+- HTTP implementation: `src/main/java/com/stripe/net/HttpURLConnectionClient.java`
+- Header management: `src/main/java/com/stripe/net/HttpHeaders.java`
+- Request building: `src/main/java/com/stripe/net/StripeRequest.java`
+- Authentication: `src/main/java/com/stripe/net/Authenticator.java`, `BearerTokenAuthenticator.java`
+- Response getter (request dispatch): `src/main/java/com/stripe/net/LiveStripeResponseGetter.java`
+- Main config/version: `src/main/java/com/stripe/Stripe.java`
+- Client class: `src/main/java/com/stripe/StripeClient.java`
+
+## Generated Code
+
+- Files containing `File generated from our OpenAPI spec` at the top are generated; do not edit. Similarly, any code block starting with `The beginning of the section generated from our OpenAPI spec` is generated and should not be edited directly.
+  - If something in a generated file/range needs to be updated, add a summary of the change to your report but don't attempt to edit it directly.
+- Resource model classes under `src/main/java/com/stripe/model/` are largely generated.
+- The `net/` package (HTTP client, headers, request/response) is NOT generated.
+
+## Conventions
+
+- Uses Java's built-in `HttpURLConnection` for HTTP
+- Requires JDK 17 to build
+- Gradle build system
+- Work is not complete until `just test` passes
+
+### Comments
+
+- Comments MUST only be used to:
+  1. Document a function
+  2. Explain the WHY of a piece of code
+  3. Explain a particularly complicated piece of code
+- Comments NEVER should be used to:
+  1. Say what used to be there. That's no longer relevant!
+  2. Explain the WHAT of a piece of code (unless it's very non-obvious)
+
+It's ok not to put comments on/in a function if their addition wouldn't meaningfully clarify anything.

.github/workflows/ci.yml

@@ -157,6 +157,7 @@ jobs:
       ((github.event_name == 'workflow_dispatch') || (github.event_name == 'push')) &&
       startsWith(github.ref, 'refs/tags/v') &&
       !contains(github.ref, 'beta') &&
+      !contains(github.ref, 'alpha') &&
       endsWith(github.actor, '-stripe')
     needs: [build, test]
     runs-on: "ubuntu-24.04"

src/main/java/com/stripe/net/HttpClient.java

@@ -13,6 +13,7 @@
 import java.util.Optional;
 import java.util.Properties;
 import java.util.concurrent.ThreadLocalRandom;
+import java.util.function.Function;
 
 /** Base abstract class for HTTP clients used to send requests to Stripe's API. */
 public abstract class HttpClient {
@@ -137,12 +138,39 @@ public StripeResponseStream requestStreamWithRetries(StripeRequest request)
     return sendWithRetries(request, (r) -> this.requestStream(r));
   }
 
+  static String detectAIAgent() {
+    return detectAIAgent(System::getenv);
+  }
+
+  static String detectAIAgent(Function<String, String> getEnv) {
+    String[][] agents = {
+      {"ANTIGRAVITY_CLI_ALIAS", "antigravity"},
+      {"CLAUDECODE", "claude_code"},
+      {"CLINE_ACTIVE", "cline"},
+      {"CODEX_SANDBOX", "codex_cli"},
+      {"CURSOR_AGENT", "cursor"},
+      {"GEMINI_CLI", "gemini_cli"},
+      {"OPENCODE", "open_code"},
+    };
+    for (String[] agent : agents) {
+      String val = getEnv.apply(agent[0]);
+      if (val != null && !val.isEmpty()) {
+        return agent[1];
+      }
+    }
+    return "";
+  }
+
   /**
    * Builds the value of the {@code User-Agent} header.
    *
    * @return a string containing the value of the {@code User-Agent} header
    */
   protected static String buildUserAgentString(StripeRequest request) {
+    return buildUserAgentString(request, detectAIAgent());
+  }
+
+  static String buildUserAgentString(StripeRequest request, String aiAgent) {
     String apiMode = request.apiMode() == ApiMode.V2 ? "v2" : "v1";
 
     String userAgent = String.format("Stripe/%s JavaBindings/%s", apiMode, Stripe.VERSION);
@@ -151,6 +179,10 @@ protected static String buildUserAgentString(StripeRequest request) {
       userAgent += " " + formatAppInfo(Stripe.getAppInfo());
     }
 
+    if (!aiAgent.isEmpty()) {
+      userAgent += " AIAgent/" + aiAgent;
+    }
+
     return userAgent;
   }
 
@@ -160,6 +192,10 @@ protected static String buildUserAgentString(StripeRequest request) {
    * @return a string containing the value of the {@code X-Stripe-Client-User-Agent} header
    */
   protected static String buildXStripeClientUserAgentString() {
+    return buildXStripeClientUserAgentString(detectAIAgent());
+  }
+
+  static String buildXStripeClientUserAgentString(String aiAgent) {
     String[] propertyNames = {
       "os.name",
       "os.version",
@@ -182,6 +218,10 @@ protected static String buildXStripeClientUserAgentString() {
     }
     getGsonVersion().ifPresent(ver -> propertyMap.put("gson.version", ver));
 
+    if (!aiAgent.isEmpty()) {
+      propertyMap.put("ai_agent", aiAgent);
+    }
+
     return ApiResource.INTERNAL_GSON.toJson(propertyMap);
   }
 

src/test/java/com/stripe/net/HttpClientTest.java

@@ -192,9 +192,8 @@ public void testV1RequestSetsCorrectUserAgent() throws StripeException {
             RequestOptions.builder().setApiKey("sk_test_123").setMaxNetworkRetries(2).build(),
             ApiMode.V1);
 
-    assertEquals(
-        HttpClient.buildUserAgentString(request),
-        String.format("Stripe/v1 JavaBindings/%s", Stripe.VERSION));
+    String userAgent = HttpClient.buildUserAgentString(request);
+    assertTrue(userAgent.startsWith(String.format("Stripe/v1 JavaBindings/%s", Stripe.VERSION)));
   }
 
   @Test
@@ -207,8 +206,52 @@ public void testV2RequestSetsCorrectUserAgent() throws StripeException {
             RequestOptions.builder().setApiKey("sk_test_123").setMaxNetworkRetries(2).build(),
             ApiMode.V2);
 
-    assertEquals(
-        HttpClient.buildUserAgentString(request),
-        String.format("Stripe/v2 JavaBindings/%s", Stripe.VERSION));
+    String userAgent = HttpClient.buildUserAgentString(request);
+    assertTrue(userAgent.startsWith(String.format("Stripe/v2 JavaBindings/%s", Stripe.VERSION)));
+  }
+
+  @Test
+  public void testDetectAIAgent() {
+    String agent = HttpClient.detectAIAgent(key -> key.equals("CLAUDECODE") ? "1" : null);
+    assertEquals("claude_code", agent);
+  }
+
+  @Test
+  public void testDetectAIAgentNoEnv() {
+    String agent = HttpClient.detectAIAgent(key -> null);
+    assertEquals("", agent);
+  }
+
+  @Test
+  public void testDetectAIAgentFirstMatchWins() {
+    String agent =
+        HttpClient.detectAIAgent(
+            key -> {
+              if (key.equals("CURSOR_AGENT") || key.equals("OPENCODE")) return "1";
+              return null;
+            });
+    assertEquals("cursor", agent);
+  }
+
+  @Test
+  public void testBuildUserAgentStringWithAIAgent() throws StripeException {
+    StripeRequest request =
+        StripeRequest.create(
+            ApiResource.RequestMethod.GET,
+            "http://example.com/get",
+            null,
+            RequestOptions.builder().setApiKey("sk_test_123").build(),
+            ApiMode.V1);
+
+    String userAgent = HttpClient.buildUserAgentString(request, "cursor");
+    assertTrue(userAgent.contains("AIAgent/cursor"));
+  }
+
+  @Test
+  public void testBuildXStripeClientUserAgentStringWithAIAgent() {
+    String json = HttpClient.buildXStripeClientUserAgentString("cursor");
+    com.google.gson.JsonObject parsed =
+        com.google.gson.JsonParser.parseString(json).getAsJsonObject();
+    assertEquals("cursor", parsed.get("ai_agent").getAsString());
   }
 }