feat(api): manual updates

Author: stainless-app[bot]

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ on:
 
 jobs:
   lint:
-    timeout-minutes: 10
+    timeout-minutes: 15
     name: lint
     runs-on: ${{ github.repository == 'stainless-sdks/terminal-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
@@ -37,7 +37,7 @@ jobs:
       - name: Run lints
         run: ./scripts/lint
   test:
-    timeout-minutes: 10
+    timeout-minutes: 15
     name: test
     runs-on: ${{ github.repository == 'stainless-sdks/terminal-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork

.github/workflows/publish-sonatype.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Java
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           distribution: temurin
           java-version: |

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 37
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/terminal%2Fterminal-007e5b747998d674f393434855b8c2a017051933e7bf5506aa5fabbc26dbe8f4.yml
-openapi_spec_hash: 23f30ca06d5bf3eb93e26d3fd7d90091
-config_hash: 6f5c0872923f09a48196d34610023f40
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/terminal%2Fterminal-84ef614abb971e8673a8639face21c77dc72cc8f1b246e84796afcc7057e6b1b.yml
+openapi_spec_hash: d08a15c87914e11038f240f0d25d09e2
+config_hash: c6e19e8b772c386e1ba9d971019d5d89

README.md

@@ -53,21 +53,23 @@ import shop.terminal.api.client.okhttp.TerminalOkHttpClient;
 import shop.terminal.api.models.product.ProductListParams;
 import shop.terminal.api.models.product.ProductListResponse;
 
-// Configures using the `TERMINAL_BEARER_TOKEN` and `TERMINAL_BASE_URL` environment variables
+// Configures using the `terminal.bearerToken` and `terminal.baseUrl` system properties
+// Or configures using the `TERMINAL_BEARER_TOKEN` and `TERMINAL_BASE_URL` environment variables
 TerminalClient client = TerminalOkHttpClient.fromEnv();
 
 ProductListResponse products = client.product().list();
 ```
 
 ## Client configuration
 
-Configure the client using environment variables:
+Configure the client using system properties or environment variables:
 
 ```java
 import shop.terminal.api.client.TerminalClient;
 import shop.terminal.api.client.okhttp.TerminalOkHttpClient;
 
-// Configures using the `TERMINAL_BEARER_TOKEN` and `TERMINAL_BASE_URL` environment variables
+// Configures using the `terminal.bearerToken` and `terminal.baseUrl` system properties
+// Or configures using the `TERMINAL_BEARER_TOKEN` and `TERMINAL_BASE_URL` environment variables
 TerminalClient client = TerminalOkHttpClient.fromEnv();
 ```
 
@@ -89,18 +91,21 @@ import shop.terminal.api.client.TerminalClient;
 import shop.terminal.api.client.okhttp.TerminalOkHttpClient;
 
 TerminalClient client = TerminalOkHttpClient.builder()
-    // Configures using the `TERMINAL_BEARER_TOKEN` and `TERMINAL_BASE_URL` environment variables
+    // Configures using the `terminal.bearerToken` and `terminal.baseUrl` system properties
+    // Or configures using the `TERMINAL_BEARER_TOKEN` and `TERMINAL_BASE_URL` environment variables
     .fromEnv()
     .appId("My App ID")
     .build();
 ```
 
 See this table for the available options:
 
-| Setter        | Environment variable    | Required | Default value                 |
-| ------------- | ----------------------- | -------- | ----------------------------- |
-| `bearerToken` | `TERMINAL_BEARER_TOKEN` | true     | -                             |
-| `baseUrl`     | `TERMINAL_BASE_URL`     | true     | `"https://api.terminal.shop"` |
+| Setter        | System property        | Environment variable    | Required | Default value                 |
+| ------------- | ---------------------- | ----------------------- | -------- | ----------------------------- |
+| `bearerToken` | `terminal.bearerToken` | `TERMINAL_BEARER_TOKEN` | true     | -                             |
+| `baseUrl`     | `terminal.baseUrl`     | `TERMINAL_BASE_URL`     | true     | `"https://api.terminal.shop"` |
+
+System properties take precedence over environment variables.
 
 > [!TIP]
 > Don't create more than one client in the same application. Each client has a connection pool and
@@ -146,7 +151,8 @@ import shop.terminal.api.client.okhttp.TerminalOkHttpClient;
 import shop.terminal.api.models.product.ProductListParams;
 import shop.terminal.api.models.product.ProductListResponse;
 
-// Configures using the `TERMINAL_BEARER_TOKEN` and `TERMINAL_BASE_URL` environment variables
+// Configures using the `terminal.bearerToken` and `terminal.baseUrl` system properties
+// Or configures using the `TERMINAL_BEARER_TOKEN` and `TERMINAL_BASE_URL` environment variables
 TerminalClient client = TerminalOkHttpClient.fromEnv();
 
 CompletableFuture<ProductListResponse> products = client.async().product().list();
@@ -161,7 +167,8 @@ import shop.terminal.api.client.okhttp.TerminalOkHttpClientAsync;
 import shop.terminal.api.models.product.ProductListParams;
 import shop.terminal.api.models.product.ProductListResponse;
 
-// Configures using the `TERMINAL_BEARER_TOKEN` and `TERMINAL_BASE_URL` environment variables
+// Configures using the `terminal.bearerToken` and `terminal.baseUrl` system properties
+// Or configures using the `TERMINAL_BEARER_TOKEN` and `TERMINAL_BASE_URL` environment variables
 TerminalClientAsync client = TerminalOkHttpClientAsync.fromEnv();
 
 CompletableFuture<ProductListResponse> products = client.product().list();
@@ -214,6 +221,8 @@ The SDK throws custom unchecked exception types:
 
 - [`TerminalIoException`](terminal-java-core/src/main/kotlin/shop/terminal/api/errors/TerminalIoException.kt): I/O networking errors.
 
+- [`TerminalRetryableException`](terminal-java-core/src/main/kotlin/shop/terminal/api/errors/TerminalRetryableException.kt): Generic error indicating a failure that could be retried by the client.
+
 - [`TerminalInvalidDataException`](terminal-java-core/src/main/kotlin/shop/terminal/api/errors/TerminalInvalidDataException.kt): Failure to interpret successfully parsed data. For example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it from the response.
 
 - [`TerminalException`](terminal-java-core/src/main/kotlin/shop/terminal/api/errors/TerminalException.kt): Base class for all exceptions. Most errors will result in one of the previously mentioned ones, but completely generic errors may be thrown using the base class.
@@ -234,6 +243,12 @@ Or to `debug` for more verbose logging:
 $ export TERMINAL_LOG=debug
 ```
 
+## ProGuard and R8
+
+Although the SDK uses reflection, it is still usable with [ProGuard](https://github.com/Guardsquare/proguard) and [R8](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization) because `terminal-java-core` is published with a [configuration file](terminal-java-core/src/main/resources/META-INF/proguard/terminal-java-core.pro) containing [keep rules](https://www.guardsquare.com/manual/configuration/usage).
+
+ProGuard and R8 should automatically detect and use the published rules, but you can also manually copy the keep rules if necessary.
+
 ## Jackson
 
 The SDK depends on [Jackson](https://github.com/FasterXML/jackson) for JSON serialization/deserialization. It is compatible with version 2.13.4 or higher, but depends on version 2.18.2 by default.
@@ -249,7 +264,7 @@ If the SDK threw an exception, but you're _certain_ the version is compatible, t
 
 ### Retries
 
-The SDK automatically retries 2 times by default, with a short exponential backoff.
+The SDK automatically retries 2 times by default, with a short exponential backoff between requests.
 
 Only the following error types are retried:
 
@@ -259,7 +274,7 @@ Only the following error types are retried:
 - 429 Rate Limit
 - 5xx Internal
 
-The API may also explicitly instruct the SDK to retry or not retry a response.
+The API may also explicitly instruct the SDK to retry or not retry a request.
 
 To set a custom number of retries, configure the client using the `maxRetries` method:
 
@@ -318,6 +333,27 @@ TerminalClient client = TerminalOkHttpClient.builder()
     .build();
 ```
 
+### HTTPS
+
+> [!NOTE]
+> Most applications should not call these methods, and instead use the system defaults. The defaults include
+> special optimizations that can be lost if the implementations are modified.
+
+To configure how HTTPS connections are secured, configure the client using the `sslSocketFactory`, `trustManager`, and `hostnameVerifier` methods:
+
+```java
+import shop.terminal.api.client.TerminalClient;
+import shop.terminal.api.client.okhttp.TerminalOkHttpClient;
+
+TerminalClient client = TerminalOkHttpClient.builder()
+    .fromEnv()
+    // If `sslSocketFactory` is set, then `trustManager` must be set, and vice versa.
+    .sslSocketFactory(yourSSLSocketFactory)
+    .trustManager(yourTrustManager)
+    .hostnameVerifier(yourHostnameVerifier)
+    .build();
+```
+
 ### Environments
 
 The SDK sends requests to the production by default. To send requests to a different environment, configure the client like so:

settings.gradle.kts

@@ -3,4 +3,5 @@ rootProject.name = "terminal-java-root"
 include("terminal-java")
 include("terminal-java-client-okhttp")
 include("terminal-java-core")
+include("terminal-java-proguard-test")
 include("terminal-java-example")

terminal-java-client-okhttp/src/main/kotlin/shop/terminal/api/client/okhttp/OkHttpClient.kt

@@ -5,6 +5,9 @@ import java.io.InputStream
 import java.net.Proxy
 import java.time.Duration
 import java.util.concurrent.CompletableFuture
+import javax.net.ssl.HostnameVerifier
+import javax.net.ssl.SSLSocketFactory
+import javax.net.ssl.X509TrustManager
 import okhttp3.Call
 import okhttp3.Callback
 import okhttp3.HttpUrl.Companion.toHttpUrl
@@ -189,13 +192,28 @@ class OkHttpClient private constructor(private val okHttpClient: okhttp3.OkHttpC
 
         private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
+        private var sslSocketFactory: SSLSocketFactory? = null
+        private var trustManager: X509TrustManager? = null
+        private var hostnameVerifier: HostnameVerifier? = null
 
         fun timeout(timeout: Timeout) = apply { this.timeout = timeout }
 
         fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
 
         fun proxy(proxy: Proxy?) = apply { this.proxy = proxy }
 
+        fun sslSocketFactory(sslSocketFactory: SSLSocketFactory?) = apply {
+            this.sslSocketFactory = sslSocketFactory
+        }
+
+        fun trustManager(trustManager: X509TrustManager?) = apply {
+            this.trustManager = trustManager
+        }
+
+        fun hostnameVerifier(hostnameVerifier: HostnameVerifier?) = apply {
+            this.hostnameVerifier = hostnameVerifier
+        }
+
         fun build(): OkHttpClient =
             OkHttpClient(
                 okhttp3.OkHttpClient.Builder()
@@ -204,6 +222,19 @@ class OkHttpClient private constructor(private val okHttpClient: okhttp3.OkHttpC
                     .writeTimeout(timeout.write())
                     .callTimeout(timeout.request())
                     .proxy(proxy)
+                    .apply {
+                        val sslSocketFactory = sslSocketFactory
+                        val trustManager = trustManager
+                        if (sslSocketFactory != null && trustManager != null) {
+                            sslSocketFactory(sslSocketFactory, trustManager)
+                        } else {
+                            check((sslSocketFactory != null) == (trustManager != null)) {
+                                "Both or none of `sslSocketFactory` and `trustManager` must be set, but only one was set"
+                            }
+                        }
+
+                        hostnameVerifier?.let(::hostnameVerifier)
+                    }
                     .build()
                     .apply {
                         // We usually make all our requests to the same host so it makes sense to