feat: allow request timeouts to be configured via ClientOptions

[cheekychops]

Problem

BaseClient builds its OkHttpClient with no timeout overrides, so every caller gets the OkHttp defaults — 10s connect, 10s read, 10s write, and no overall call timeout — with no supported way to change them:

• Client exposes only Client(apiKey) and Client(apiKey, ClientOptions)
• ClientOptions carries the region and nothing else
• newHttpClient is private static
• the BaseClient constructors that do accept an OkHttpClient are protected, and a Client subclass cannot reach them through super(...)

So the only routes available today are reflection over BaseClient's private final OkHttpClient client field, or vendoring the SDK. Neither is something we want in a payments integration.

Why 10s read is the painful one

For an integration whose Recurly calls are mostly writes, a 10s read timeout converts a slow-but-successful response into a failure whose outcome the caller cannot determine. A createSubscription that times out at 10s may well have been applied at Recurly — so the caller cannot simply retry, and instead has to reconcile by reading back the account's subscriptions and matching them against what it asked for.

We have production evidence of exactly that: a recent burst of timed-out subscription creates all took 10.7–10.8s, and in every case the write had in fact landed — confirmed by Recurly's own new_subscription and successful_payment webhooks arriving seconds later. The customer was charged and shown an error. Being able to raise the read timeout is a far smaller thing to own than the reconciliation logic it forces.

Change

ClientOptions gains optional connectTimeout, readTimeout, writeTimeout and callTimeout (java.time.Duration), and newHttpClient applies each one that is set:

ClientOptions options = new ClientOptions();
options.setReadTimeout(Duration.ofSeconds(30));
Client client = new Client(apiKey, options);

Anything left unset behaves exactly as before, so this is source- and behaviour-compatible. newHttpClient becomes package-private so the tests can assert on the client it builds; it is not part of the public surface either way.

Tests

Four new cases in BaseClientTest:

• defaults unchanged when nothing is configured (pins the current 10s/10s/10s and no call timeout)
• all four timeouts applied when set
• timeouts applied individually, without disturbing the others
• a configured timeout surviving construction through the public Client(apiKey, ClientOptions) constructor

mvn test is green: 48 tests, 0 failures, with the existing 26 BaseClientTest cases untouched. Reverting the wiring in newHttpClient fails exactly the three tests that assert configured values, so they do bind to the change.

I could not run ./scripts/format — bin/google-java-format-1.35.0-all-deps.jar is not present in the repo — so the new code follows the surrounding style by hand and stays within 100 columns. Happy to reformat if CI disagrees.

Notes

• ClientOptions.java and BaseClient.java both lack the "automatically created by Recurly's OpenAPI generation process" banner, so I have taken them to be hand-written and in scope for a PR per CONTRIBUTING.
• I could not find an existing issue requesting this, so there is nothing to link. Happy to open one first if you would rather discuss it there.
• Related: [BUG] if server respond with 204(no content) client getting NPE here #261 and the guard in fix: guard against a null response Content-Type in BaseClient.makeRequest #338, which is the other half of what makes a timed-out write hard to reason about — the retry that follows a timeout can come back with a response the client cannot read.