Merge pull request #2189 from stripe/xavdid/merge-java-beta

Merge to beta

Author: xavdid-stripe

.github/workflows/ci.yml

@@ -72,7 +72,7 @@ jobs:
           - "25"
           # non-LTS versions
           # we should periodically add the latest non-LTS version here to test against
-          # as of 2025-09-29, the latest version of java (25) is LTS, so this section is empty. In March 2026, we'll add "26".
+          - "26"
 
     steps:
       - uses: extractions/setup-just@v2
@@ -110,8 +110,7 @@ jobs:
   publish:
     if: >-
       ((github.event_name == 'workflow_dispatch') || (github.event_name == 'push')) &&
-      startsWith(github.ref, 'refs/tags/v') &&
-      endsWith(github.actor, '-stripe')
+      startsWith(github.ref, 'refs/tags/v')
     needs: [build, test]
     runs-on: "ubuntu-24.04"
     permissions:
@@ -153,12 +152,11 @@ 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')
+      !contains(github.ref, 'alpha')
     needs: [build, test]
     runs-on: "ubuntu-24.04"
     permissions:
-        contents: write
+      contents: write
     steps:
       - uses: actions/checkout@master
       - name: Setup Java

README.md

@@ -4,6 +4,9 @@
 [![JavaDoc](http://img.shields.io/badge/javadoc-reference-blue.svg)](https://stripe.dev/stripe-java)
 [![Build Status](https://github.com/stripe/stripe-java/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/stripe/stripe-java/actions?query=branch%3Amaster)
 
+> [!TIP]
+> Want to chat live with Stripe engineers? Join us on our [Discord server](https://stripe.com/go/discord/java).
+
 The official [Stripe][stripe] Java client library.
 
 ## Installation

build.gradle

@@ -100,7 +100,7 @@ jar {
                    "Implementation-Vendor": VENDOR_NAME,
                    "Bundle-SymbolicName": POM_ARTIFACT_ID,
                    "Export-Package": "com.stripe.*",
-                   "Automatic-Module-Name": "stripe.java")
+                   "Automatic-Module-Name": "com.stripe")
 
         archiveVersion = VERSION_NAME
     }

justfile

@@ -5,6 +5,10 @@ import? '../sdk-codegen/utils.just'
 _default:
     just --list --unsorted
 
+# ⭐ run format and tests to prepare for CI
+[no-exit-message]
+prepare: format test
+
 # ⭐ run the whole test suite
 [no-exit-message]
 test *args:

src/main/java/com/stripe/StripeClient.java

@@ -1197,6 +1197,7 @@ public static final class StripeClientBuilder {
     private String meterEventsBase = Stripe.METER_EVENTS_API_BASE;
     private String stripeAccount;
     private String stripeContext;
+    private HttpClient httpClient;
 
     /**
      * Constructs a request options builder with the global parameters (API key and client ID) as
@@ -1208,19 +1209,29 @@ public Authenticator getAuthenticator() {
       return this.authenticator;
     }
 
+    /**
+     * Sets the authenticator used to authorize requests. Use this for custom authentication
+     * strategies. For standard API key authentication, prefer {@link #setApiKey(String)}.
+     *
+     * <p>This shares a backing field with {@link #setApiKey(String)} — calling one overwrites the
+     * other.
+     *
+     * @param authenticator the authenticator to use
+     */
     public StripeClientBuilder setAuthenticator(Authenticator authenticator) {
       this.authenticator = authenticator;
       return this;
     }
 
-    public String getApiKey() {
-      if (authenticator instanceof BearerTokenAuthenticator) {
-        return ((BearerTokenAuthenticator) authenticator).getApiKey();
-      }
-
-      return null;
-    }
-
+    /**
+     * Sets the API key for bearer token authentication. This is a convenience method equivalent to
+     * calling {@code setAuthenticator(new BearerTokenAuthenticator(apiKey))}.
+     *
+     * <p>This shares a backing field with {@link #setAuthenticator(Authenticator)} — calling one
+     * overwrites the other.
+     *
+     * @param apiKey the API key; if null, clears the authenticator
+     */
     public StripeClientBuilder setApiKey(String apiKey) {
       if (apiKey == null) {
         this.authenticator = null;
@@ -1328,7 +1339,8 @@ public StripeClientBuilder setProxyCredential(PasswordAuthentication proxyCreden
      * Set the base URL for the Stripe API. By default this is "https://api.stripe.com".
      *
      * <p>This only affects requests made with a {@link com.stripe.net.BaseAddress} of API. Use
-     * {@link setFilesBase} or {@link setConnectBase} to interpect requests with other bases.
+     * {@link #setFilesBase}, {@link #setConnectBase} or {@link #setMeterEventsBase} to interpect
+     * requests with other bases.
      */
     public StripeClientBuilder setApiBase(String address) {
       this.apiBase = address;
@@ -1405,9 +1417,23 @@ public String getStripeContext() {
       return this.stripeContext;
     }
 
+    /**
+     * Sets the HTTP client to use for making requests to the Stripe API. If not set, a default
+     * {@link HttpURLConnectionClient} will be created.
+     *
+     * <p>This is useful for providing a custom HTTP client implementation, e.g. for testing or for
+     * using a different HTTP library.
+     *
+     * @param httpClient the HTTP client to use
+     */
+    public StripeClientBuilder setHttpClient(HttpClient httpClient) {
+      this.httpClient = httpClient;
+      return this;
+    }
+
     /** Constructs a {@link StripeResponseGetterOptions} with the specified values. */
     public StripeClient build() {
-      return new StripeClient(new LiveStripeResponseGetter(buildOptions(), null));
+      return new StripeClient(new LiveStripeResponseGetter(buildOptions(), this.httpClient));
     }
 
     StripeResponseGetterOptions buildOptions() {

src/main/java/com/stripe/model/StringInt64TypeAdapter.java

@@ -0,0 +1,31 @@
+package com.stripe.model;
+
+import com.google.gson.TypeAdapter;
+import com.google.gson.stream.JsonReader;
+import com.google.gson.stream.JsonToken;
+import com.google.gson.stream.JsonWriter;
+import java.io.IOException;
+
+public class StringInt64TypeAdapter extends TypeAdapter<Long> {
+  /** Serializes Long values as JSON strings and deserializes string-encoded integers. */
+  @Override
+  public void write(JsonWriter out, Long value) throws IOException {
+    if (value == null) {
+      out.nullValue();
+      return;
+    }
+
+    out.value(value.toString());
+  }
+
+  @Override
+  public Long read(JsonReader in) throws IOException {
+    JsonToken token = in.peek();
+    if (token == JsonToken.NULL) {
+      in.nextNull();
+      return null;
+    }
+
+    return Long.valueOf(in.nextString());
+  }
+}

src/main/java/com/stripe/model/v2/core/Event.java

@@ -99,7 +99,7 @@ protected StripeObject fetchRelatedObject(RelatedObject relatedObject) throws St
     }
 
     RequestOptions.RequestOptionsBuilder optsBuilder = new RequestOptions.RequestOptionsBuilder();
-    // optsBuilder.setStripeRequestTrigger("event=" + id); // TODO https://go/j/DEVSDK-3018
+    optsBuilder.setStripeRequestTrigger("event=" + id);
 
     if (context != null) {
       optsBuilder.setStripeAccount(context);

src/main/java/com/stripe/model/v2/core/EventNotification.java

@@ -106,12 +106,12 @@ public static EventNotification fromJson(String payload, StripeClient client) {
   }
 
   private RawRequestOptions getRequestOptions() {
-    if (context == null) {
-      return null;
+    RawRequestOptions.RawRequestOptionsBuilder builder =
+        RawRequestOptions.builder().setStripeRequestTrigger("event=" + id);
+    if (context != null) {
+      builder.setStripeContext(context.toString());
     }
-    return new RawRequestOptions.RawRequestOptionsBuilder()
-        .setStripeContext(context.toString())
-        .build();
+    return builder.build();
   }
 
   /* retrieves the full payload for an event. Protected because individual push classes use it, but type it correctly */

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

@@ -2,7 +2,16 @@
 
 import com.stripe.exception.StripeException;
 
-/** * Represents a request authentication mechanism. */
+/**
+ * Interface for applying authentication to a request. This is used by {@link StripeResponseGetter}
+ * to apply authentication to requests before they are sent. Implementations of this interface
+ * should not modify the request in-place, but should instead return a new request with the
+ * appropriate authentication headers applied. The default implementation of this interface is
+ * {@link BearerTokenAuthenticator}, which applies the API key as a Bearer token in the
+ * Authorization header. Users can also implement this interface to provide custom authentication
+ * logic, often by wrapping the BearerTokenAuthenticator and applying additional headers or logic as
+ * needed.
+ */
 public interface Authenticator {
   /**
    * * Authenticate the request

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

@@ -8,34 +8,9 @@
 public class RawRequestOptions extends RequestOptions {
   private Map<String, String> additionalHeaders;
 
-  public RawRequestOptions(
-      Authenticator authenticator,
-      String clientId,
-      String idempotencyKey,
-      String stripeContext,
-      String stripeAccount,
-      String stripeVersionOverride,
-      String baseUrl,
-      Integer connectTimeout,
-      Integer readTimeout,
-      Integer maxNetworkRetries,
-      Proxy connectionProxy,
-      PasswordAuthentication proxyCredential,
-      Map<String, String> additionalHeaders) {
-    super(
-        authenticator,
-        clientId,
-        idempotencyKey,
-        stripeContext,
-        stripeAccount,
-        stripeVersionOverride,
-        baseUrl,
-        connectTimeout,
-        readTimeout,
-        maxNetworkRetries,
-        connectionProxy,
-        proxyCredential);
-    this.additionalHeaders = additionalHeaders;
+  private RawRequestOptions(RawRequestOptionsBuilder builder) {
+    super(builder);
+    this.additionalHeaders = builder.additionalHeaders;
   }
 
   public Map<String, String> getAdditionalHeaders() {
@@ -88,6 +63,12 @@ public RawRequestOptionsBuilder setStripeContext(StripeContext stripeContext) {
       return this;
     }
 
+    @Override
+    public RawRequestOptionsBuilder setStripeRequestTrigger(String stripeRequestTrigger) {
+      super.setStripeRequestTrigger(stripeRequestTrigger);
+      return this;
+    }
+
     @Override
     public RawRequestOptionsBuilder setStripeAccount(String stripeAccount) {
       super.setStripeAccount(stripeAccount);
@@ -132,20 +113,7 @@ public RawRequestOptionsBuilder setProxyCredential(PasswordAuthentication proxyC
 
     @Override
     public RawRequestOptions build() {
-      return new RawRequestOptions(
-          authenticator,
-          normalizeClientId(this.clientId),
-          normalizeIdempotencyKey(this.idempotencyKey),
-          normalizeStripeContext(this.stripeContext),
-          normalizeStripeAccount(this.stripeAccount),
-          normalizeStripeVersion(this.stripeVersionOverride),
-          normalizeBaseUrl(this.baseUrl),
-          connectTimeout,
-          readTimeout,
-          maxNetworkRetries,
-          connectionProxy,
-          proxyCredential,
-          additionalHeaders);
+      return new RawRequestOptions(this);
     }
   }
 }