feat(api): updates

Author: stainless-app[bot]

.github/workflows/ci.yml

@@ -1,18 +1,18 @@
 name: CI
 on:
   push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-      - next
+    branches-ignore:
+      - 'generated'
+      - 'codegen/**'
+      - 'integrated/**'
+      - 'stl-preview-head/**'
+      - 'stl-preview-base/**'
 
 jobs:
   lint:
+    timeout-minutes: 10
     name: lint
-    runs-on: ubuntu-latest
-    
+    runs-on: ${{ github.repository == 'stainless-sdks/open-transit-kotlin' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
 
     steps:
       - uses: actions/checkout@v4
@@ -23,7 +23,7 @@ jobs:
           distribution: temurin
           java-version: |
             8
-            17
+            21
           cache: gradle
 
       - name: Set up Gradle
@@ -32,9 +32,9 @@ jobs:
       - name: Run lints
         run: ./scripts/lint
   test:
+    timeout-minutes: 10
     name: test
-    runs-on: ubuntu-latest
-
+    runs-on: ${{ github.repository == 'stainless-sdks/open-transit-kotlin' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@v4
 
@@ -44,7 +44,7 @@ jobs:
           distribution: temurin
           java-version: |
             8
-            17
+            21
           cache: gradle
 
       - name: Set up Gradle

.github/workflows/publish-sonatype.yml

@@ -33,7 +33,7 @@ jobs:
           export -- GPG_SIGNING_KEY_ID
           printenv -- GPG_SIGNING_KEY | gpg --batch --passphrase-fd 3 --import 3<<< "$GPG_SIGNING_PASSWORD"
           GPG_SIGNING_KEY_ID="$(gpg --with-colons --list-keys | awk -F : -- '/^pub:/ { getline; print "0x" substr($10, length($10) - 7) }')"
-          ./gradlew publishAndReleaseToMavenCentral --stacktrace -PmavenCentralUsername="$SONATYPE_USERNAME" -PmavenCentralPassword="$SONATYPE_PASSWORD"
+          ./gradlew publishAndReleaseToMavenCentral --stacktrace -PmavenCentralUsername="$SONATYPE_USERNAME" -PmavenCentralPassword="$SONATYPE_PASSWORD" --no-configuration-cache
         env:
           SONATYPE_USERNAME: ${{ secrets.ONEBUSAWAY_SDK_SONATYPE_USERNAME || secrets.SONATYPE_USERNAME }}
           SONATYPE_PASSWORD: ${{ secrets.ONEBUSAWAY_SDK_SONATYPE_PASSWORD || secrets.SONATYPE_PASSWORD }}

.stats.yml

@@ -1,2 +1,4 @@
 configured_endpoints: 29
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/open-transit%2Fopen-transit-6f08502508c8ad25235971add3124a1cde4f1c3ec705d5df455d750e0adcb90b.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/open-transit%2Fopen-transit-4fcbe9547537b22a2d68329e1d94e0c1a6f81b5af734ca213f7b95eef5da7adb.yml
+openapi_spec_hash: 417ea17b08e186b15b2986372592185e
+config_hash: 3871f5d21bb38ddd334ec04721dea64d

README.md

@@ -15,7 +15,7 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 <!-- x-release-please-start-version -->
 
-The REST API documentation can be found on [developer.onebusaway.org](https://developer.onebusaway.org). KDocs are also available on [javadoc.io](https://javadoc.io/doc/org.onebusaway/onebusaway-sdk-kotlin/0.1.0-alpha.66).
+The REST API documentation can be found on [developer.onebusaway.org](https://developer.onebusaway.org). KDocs are available on [javadoc.io](https://javadoc.io/doc/org.onebusaway/onebusaway-sdk-kotlin/0.1.0-alpha.69).
 
 <!-- x-release-please-end -->
 
@@ -33,9 +33,9 @@ implementation("org.onebusaway:onebusaway-sdk-kotlin:0.1.0-alpha.69")
 
 ```xml
 <dependency>
-    <groupId>org.onebusaway</groupId>
-    <artifactId>onebusaway-sdk-kotlin</artifactId>
-    <version>0.1.0-alpha.69</version>
+  <groupId>org.onebusaway</groupId>
+  <artifactId>onebusaway-sdk-kotlin</artifactId>
+  <version>0.1.0-alpha.69</version>
 </dependency>
 ```
 
@@ -50,10 +50,10 @@ This library requires Java 8 or later.
 ```kotlin
 import org.onebusaway.client.OnebusawaySdkClient
 import org.onebusaway.client.okhttp.OnebusawaySdkOkHttpClient
-import org.onebusaway.models.CurrentTimeRetrieveParams
-import org.onebusaway.models.CurrentTimeRetrieveResponse
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveParams
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveResponse
 
-// Configures using the `ONEBUSAWAY_API_KEY` environment variable
+// Configures using the `ONEBUSAWAY_API_KEY` and `ONEBUSAWAY_SDK_BASE_URL` environment variables
 val client: OnebusawaySdkClient = OnebusawaySdkOkHttpClient.fromEnv()
 
 val currentTime: CurrentTimeRetrieveResponse = client.currentTime().retrieve()
@@ -67,7 +67,7 @@ Configure the client using environment variables:
 import org.onebusaway.client.OnebusawaySdkClient
 import org.onebusaway.client.okhttp.OnebusawaySdkOkHttpClient
 
-// Configures using the `ONEBUSAWAY_API_KEY` environment variable
+// Configures using the `ONEBUSAWAY_API_KEY` and `ONEBUSAWAY_SDK_BASE_URL` environment variables
 val client: OnebusawaySdkClient = OnebusawaySdkOkHttpClient.fromEnv()
 ```
 
@@ -89,17 +89,18 @@ import org.onebusaway.client.OnebusawaySdkClient
 import org.onebusaway.client.okhttp.OnebusawaySdkOkHttpClient
 
 val client: OnebusawaySdkClient = OnebusawaySdkOkHttpClient.builder()
-    // Configures using the `ONEBUSAWAY_API_KEY` environment variable
+    // Configures using the `ONEBUSAWAY_API_KEY` and `ONEBUSAWAY_SDK_BASE_URL` environment variables
     .fromEnv()
     .apiKey("My API Key")
     .build()
 ```
 
 See this table for the available options:
 
-| Setter   | Environment variable | Required | Default value |
-| -------- | -------------------- | -------- | ------------- |
-| `apiKey` | `ONEBUSAWAY_API_KEY` | true     | -             |
+| Setter    | Environment variable      | Required | Default value                             |
+| --------- | ------------------------- | -------- | ----------------------------------------- |
+| `apiKey`  | `ONEBUSAWAY_API_KEY`      | true     | -                                         |
+| `baseUrl` | `ONEBUSAWAY_SDK_BASE_URL` | true     | `"https://api.pugetsound.onebusaway.org"` |
 
 > [!TIP]
 > Don't create more than one client in the same application. Each client has a connection pool and
@@ -126,10 +127,10 @@ The default client is synchronous. To switch to asynchronous execution, call the
 ```kotlin
 import org.onebusaway.client.OnebusawaySdkClient
 import org.onebusaway.client.okhttp.OnebusawaySdkOkHttpClient
-import org.onebusaway.models.CurrentTimeRetrieveParams
-import org.onebusaway.models.CurrentTimeRetrieveResponse
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveParams
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveResponse
 
-// Configures using the `ONEBUSAWAY_API_KEY` environment variable
+// Configures using the `ONEBUSAWAY_API_KEY` and `ONEBUSAWAY_SDK_BASE_URL` environment variables
 val client: OnebusawaySdkClient = OnebusawaySdkOkHttpClient.fromEnv()
 
 val currentTime: CurrentTimeRetrieveResponse = client.async().currentTime().retrieve()
@@ -140,10 +141,10 @@ Or create an asynchronous client from the beginning:
 ```kotlin
 import org.onebusaway.client.OnebusawaySdkClientAsync
 import org.onebusaway.client.okhttp.OnebusawaySdkOkHttpClientAsync
-import org.onebusaway.models.CurrentTimeRetrieveParams
-import org.onebusaway.models.CurrentTimeRetrieveResponse
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveParams
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveResponse
 
-// Configures using the `ONEBUSAWAY_API_KEY` environment variable
+// Configures using the `ONEBUSAWAY_API_KEY` and `ONEBUSAWAY_SDK_BASE_URL` environment variables
 val client: OnebusawaySdkClientAsync = OnebusawaySdkOkHttpClientAsync.fromEnv()
 
 val currentTime: CurrentTimeRetrieveResponse = client.currentTime().retrieve()
@@ -160,8 +161,8 @@ To access this data, prefix any HTTP method call on a client or service with `wi
 ```kotlin
 import org.onebusaway.core.http.Headers
 import org.onebusaway.core.http.HttpResponseFor
-import org.onebusaway.models.CurrentTimeRetrieveParams
-import org.onebusaway.models.CurrentTimeRetrieveResponse
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveParams
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveResponse
 
 val currentTime: HttpResponseFor<CurrentTimeRetrieveResponse> = client.currentTime().withRawResponse().retrieve()
 
@@ -172,7 +173,7 @@ val headers: Headers = currentTime.headers()
 You can still deserialize the response into an instance of a Kotlin class if needed:
 
 ```kotlin
-import org.onebusaway.models.CurrentTimeRetrieveResponse
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveResponse
 
 val parsedCurrentTime: CurrentTimeRetrieveResponse = currentTime.parse()
 ```
@@ -216,6 +217,17 @@ Or to `debug` for more verbose logging:
 $ export ONEBUSAWAY_SDK_LOG=debug
 ```
 
+## 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.
+
+The SDK throws an exception if it detects an incompatible Jackson version at runtime (e.g. if the default version was overridden in your Maven or Gradle config).
+
+If the SDK threw an exception, but you're _certain_ the version is compatible, then disable the version check using the `checkJacksonVersionCompatibility` on [`OnebusawaySdkOkHttpClient`](onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClient.kt) or [`OnebusawaySdkOkHttpClientAsync`](onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClientAsync.kt).
+
+> [!CAUTION]
+> We make no guarantee that the SDK works correctly when the Jackson version check is disabled.
+
 ## Network options
 
 ### Retries
@@ -251,8 +263,7 @@ Requests time out after 1 minute by default.
 To set a custom timeout, configure the method call using the `timeout` method:
 
 ```kotlin
-import org.onebusaway.models.CurrentTimeRetrieveParams
-import org.onebusaway.models.CurrentTimeRetrieveResponse
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveResponse
 
 val currentTime: CurrentTimeRetrieveResponse = client.currentTime().retrieve(RequestOptions.builder().timeout(Duration.ofSeconds(30)).build())
 ```
@@ -290,6 +301,42 @@ val client: OnebusawaySdkClient = OnebusawaySdkOkHttpClient.builder()
     .build()
 ```
 
+### Custom HTTP client
+
+The SDK consists of three artifacts:
+
+- `onebusaway-sdk-kotlin-core`
+  - Contains core SDK logic
+  - Does not depend on [OkHttp](https://square.github.io/okhttp)
+  - Exposes [`OnebusawaySdkClient`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClient.kt), [`OnebusawaySdkClientAsync`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientAsync.kt), [`OnebusawaySdkClientImpl`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientImpl.kt), and [`OnebusawaySdkClientAsyncImpl`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientAsyncImpl.kt), all of which can work with any HTTP client
+- `onebusaway-sdk-kotlin-client-okhttp`
+  - Depends on [OkHttp](https://square.github.io/okhttp)
+  - Exposes [`OnebusawaySdkOkHttpClient`](onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClient.kt) and [`OnebusawaySdkOkHttpClientAsync`](onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClientAsync.kt), which provide a way to construct [`OnebusawaySdkClientImpl`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientImpl.kt) and [`OnebusawaySdkClientAsyncImpl`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientAsyncImpl.kt), respectively, using OkHttp
+- `onebusaway-sdk-kotlin`
+  - Depends on and exposes the APIs of both `onebusaway-sdk-kotlin-core` and `onebusaway-sdk-kotlin-client-okhttp`
+  - Does not have its own logic
+
+This structure allows replacing the SDK's default HTTP client without pulling in unnecessary dependencies.
+
+#### Customized [`OkHttpClient`](https://square.github.io/okhttp/3.x/okhttp/okhttp3/OkHttpClient.html)
+
+> [!TIP]
+> Try the available [network options](#network-options) before replacing the default client.
+
+To use a customized `OkHttpClient`:
+
+1. Replace your [`onebusaway-sdk-kotlin` dependency](#installation) with `onebusaway-sdk-kotlin-core`
+2. Copy `onebusaway-sdk-kotlin-client-okhttp`'s [`OkHttpClient`](onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OkHttpClient.kt) class into your code and customize it
+3. Construct [`OnebusawaySdkClientImpl`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientImpl.kt) or [`OnebusawaySdkClientAsyncImpl`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientAsyncImpl.kt), similarly to [`OnebusawaySdkOkHttpClient`](onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClient.kt) or [`OnebusawaySdkOkHttpClientAsync`](onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClientAsync.kt), using your customized client
+
+### Completely custom HTTP client
+
+To use a completely custom HTTP client:
+
+1. Replace your [`onebusaway-sdk-kotlin` dependency](#installation) with `onebusaway-sdk-kotlin-core`
+2. Write a class that implements the [`HttpClient`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/core/http/HttpClient.kt) interface
+3. Construct [`OnebusawaySdkClientImpl`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientImpl.kt) or [`OnebusawaySdkClientAsyncImpl`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/client/OnebusawaySdkClientAsyncImpl.kt), similarly to [`OnebusawaySdkOkHttpClient`](onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClient.kt) or [`OnebusawaySdkOkHttpClientAsync`](onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClientAsync.kt), using your new client class
+
 ## Undocumented API functionality
 
 The SDK is typed for convenient usage of the documented API. However, it also supports working with undocumented or not yet supported parts of the API.
@@ -300,7 +347,7 @@ To set undocumented parameters, call the `putAdditionalHeader`, `putAdditionalQu
 
 ```kotlin
 import org.onebusaway.core.JsonValue
-import org.onebusaway.models.CurrentTimeRetrieveParams
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveParams
 
 val params: CurrentTimeRetrieveParams = CurrentTimeRetrieveParams.builder()
     .putAdditionalHeader("Secret-Header", "42")
@@ -314,7 +361,7 @@ These can be accessed on the built object later using the `_additionalHeaders()`
 To set a documented parameter or property to an undocumented or not yet supported _value_, pass a [`JsonValue`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/core/Values.kt) object to its setter:
 
 ```kotlin
-import org.onebusaway.models.CurrentTimeRetrieveParams
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveParams
 
 val params: CurrentTimeRetrieveParams = CurrentTimeRetrieveParams.builder().build()
 ```
@@ -354,6 +401,20 @@ val complexValue: JsonValue = JsonValue.from(mapOf(
 ))
 ```
 
+Normally a `Builder` class's `build` method will throw [`IllegalStateException`](https://docs.oracle.com/javase/8/docs/api/java/lang/IllegalStateException.html) if any required parameter or property is unset.
+
+To forcibly omit a required parameter or property, pass [`JsonMissing`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/core/Values.kt):
+
+```kotlin
+import org.onebusaway.core.JsonMissing
+import org.onebusaway.models.agency.AgencyRetrieveParams
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveParams
+
+val params: CurrentTimeRetrieveParams = AgencyRetrieveParams.builder()
+    .agencyId(JsonMissing.of())
+    .build()
+```
+
 ### Response properties
 
 To access undocumented response properties, call the `_additionalProperties()` method:
@@ -406,16 +467,15 @@ By default, the SDK will not throw an exception in this case. It will throw [`On
 If you would prefer to check that the response is completely well-typed upfront, then either call `validate()`:
 
 ```kotlin
-import org.onebusaway.models.CurrentTimeRetrieveResponse
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveResponse
 
 val currentTime: CurrentTimeRetrieveResponse = client.currentTime().retrieve(params).validate()
 ```
 
 Or configure the method call to validate the response using the `responseValidation` method:
 
 ```kotlin
-import org.onebusaway.models.CurrentTimeRetrieveParams
-import org.onebusaway.models.CurrentTimeRetrieveResponse
+import org.onebusaway.models.currenttime.CurrentTimeRetrieveResponse
 
 val currentTime: CurrentTimeRetrieveResponse = client.currentTime().retrieve(RequestOptions.builder().responseValidation(true).build())
 ```

buildSrc/src/main/kotlin/onebusaway-sdk.kotlin.gradle.kts

@@ -9,7 +9,7 @@ plugins {
 
 kotlin {
     jvmToolchain {
-        languageVersion.set(JavaLanguageVersion.of(17))
+        languageVersion.set(JavaLanguageVersion.of(21))
     }
 
     compilerOptions {
@@ -34,8 +34,7 @@ configure<SpotlessExtension> {
     }
 }
 
-// Run tests in parallel to some degree.
 tasks.withType<Test>().configureEach {
-    maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).coerceAtLeast(1)
-    forkEvery = 100
+    systemProperty("junit.jupiter.execution.parallel.enabled", true)
+    systemProperty("junit.jupiter.execution.parallel.mode.default", "concurrent")
 }

gradle.properties

@@ -1,5 +1,17 @@
 org.gradle.caching=true
+org.gradle.configuration-cache=true
 org.gradle.parallel=true
 org.gradle.daemon=false
-org.gradle.jvmargs=-Xmx4g
-kotlin.daemon.jvmargs=-Xmx4g
+# These options improve our compilation and test performance. They are inherited by the Kotlin daemon.
+org.gradle.jvmargs=\
+  -Xms1g \
+  -Xmx4g \
+  -XX:+UseParallelGC \
+  -XX:InitialCodeCacheSize=256m \
+  -XX:ReservedCodeCacheSize=1G \
+  -XX:MetaspaceSize=256m \
+  -XX:TieredStopAtLevel=1 \
+  -XX:GCTimeRatio=4 \
+  -XX:CICompilerCount=4 \
+  -XX:+OptimizeStringConcat \
+  -XX:+UseStringDeduplication

onebusaway-sdk-kotlin-client-okhttp/src/main/kotlin/org/onebusaway/client/okhttp/OnebusawaySdkOkHttpClient.kt

@@ -29,13 +29,20 @@ class OnebusawaySdkOkHttpClient private constructor() {
     class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
-        private var baseUrl: String = ClientOptions.PRODUCTION_URL
         private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
 
-        fun baseUrl(baseUrl: String) = apply {
-            clientOptions.baseUrl(baseUrl)
-            this.baseUrl = baseUrl
+        fun baseUrl(baseUrl: String) = apply { clientOptions.baseUrl(baseUrl) }
+
+        /**
+         * Whether to throw an exception if any of the Jackson versions detected at runtime are
+         * incompatible with the SDK's minimum supported Jackson version (2.13.4).
+         *
+         * Defaults to true. Use extreme caution when disabling this option. There is no guarantee
+         * that the SDK will work correctly when using an incompatible Jackson version.
+         */
+        fun checkJacksonVersionCompatibility(checkJacksonVersionCompatibility: Boolean) = apply {
+            clientOptions.checkJacksonVersionCompatibility(checkJacksonVersionCompatibility)
         }
 
         fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
@@ -158,7 +165,7 @@ class OnebusawaySdkOkHttpClient private constructor() {
                 clientOptions
                     .httpClient(
                         OkHttpClient.builder()
-                            .baseUrl(baseUrl)
+                            .baseUrl(clientOptions.baseUrl())
                             .timeout(timeout)
                             .proxy(proxy)
                             .build()