Merge pull request #309 from OneBusAway/release-please--branches--main--changes--next

release: 0.1.0-alpha.68

Author: Ahmedhossamdev

.gitignore

@@ -1,6 +1,7 @@
 .prism.log
 .gradle
 .idea
+.kotlin
 build
 codegen.log
 kls_database.db

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.67"
+  ".": "0.1.0-alpha.68"
 }

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.0-alpha.68 (2025-05-15)
+
+Full Changelog: [v0.1.0-alpha.67...v0.1.0-alpha.68](https://github.com/OneBusAway/kotlin-sdk/compare/v0.1.0-alpha.67...v0.1.0-alpha.68)
+
+### Chores
+
+* **internal:** add `.kotlin` to `.gitignore` ([#276](https://github.com/OneBusAway/kotlin-sdk/issues/276)) ([1eb24ad](https://github.com/OneBusAway/kotlin-sdk/commit/1eb24ad47b637a551e3bfe075e8146c707c60019))
+* **internal:** codegen related update ([#277](https://github.com/OneBusAway/kotlin-sdk/issues/277)) ([df01249](https://github.com/OneBusAway/kotlin-sdk/commit/df01249a07ee2d58d49e3328dfe024ae5074773a))
+
+
+### Documentation
+
+* document `JsonValue` construction in readme ([#279](https://github.com/OneBusAway/kotlin-sdk/issues/279)) ([d093175](https://github.com/OneBusAway/kotlin-sdk/commit/d093175f95faf5270b78715ecfe863cfbd665ac7))
+* revise readme docs about nested params ([#278](https://github.com/OneBusAway/kotlin-sdk/issues/278)) ([0d9b03e](https://github.com/OneBusAway/kotlin-sdk/commit/0d9b03e374779e83a960842653f4e75734736d23))
+
 ## 0.1.0-alpha.67 (2025-05-15)
 
 Full Changelog: [v0.1.0-alpha.66...v0.1.0-alpha.67](https://github.com/OneBusAway/kotlin-sdk/compare/v0.1.0-alpha.66...v0.1.0-alpha.67)

README.md

@@ -2,8 +2,8 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/org.onebusaway/onebusaway-sdk-kotlin)](https://central.sonatype.com/artifact/org.onebusaway/onebusaway-sdk-kotlin/0.1.0-alpha.67)
-[![javadoc](https://javadoc.io/badge2/org.onebusaway/onebusaway-sdk-kotlin/0.1.0-alpha.67/javadoc.svg)](https://javadoc.io/doc/org.onebusaway/onebusaway-sdk-kotlin/0.1.0-alpha.67)
+[![Maven Central](https://img.shields.io/maven-central/v/org.onebusaway/onebusaway-sdk-kotlin)](https://central.sonatype.com/artifact/org.onebusaway/onebusaway-sdk-kotlin/0.1.0-alpha.68)
+[![javadoc](https://javadoc.io/badge2/org.onebusaway/onebusaway-sdk-kotlin/0.1.0-alpha.68/javadoc.svg)](https://javadoc.io/doc/org.onebusaway/onebusaway-sdk-kotlin/0.1.0-alpha.68)
 
 <!-- x-release-please-end -->
 
@@ -22,7 +22,7 @@ The REST API documentation can be found on [developer.onebusaway.org](https://de
 ### Gradle
 
 ```kotlin
-implementation("org.onebusaway:onebusaway-sdk-kotlin:0.1.0-alpha.67")
+implementation("org.onebusaway:onebusaway-sdk-kotlin:0.1.0-alpha.68")
 ```
 
 ### Maven
@@ -31,7 +31,7 @@ implementation("org.onebusaway:onebusaway-sdk-kotlin:0.1.0-alpha.67")
 <dependency>
     <groupId>org.onebusaway</groupId>
     <artifactId>onebusaway-sdk-kotlin</artifactId>
-    <version>0.1.0-alpha.67</version>
+    <version>0.1.0-alpha.68</version>
 </dependency>
 ```
 
@@ -305,16 +305,51 @@ val params: CurrentTimeRetrieveParams = CurrentTimeRetrieveParams.builder()
     .build()
 ```
 
-These can be accessed on the built object later using the `_additionalHeaders()`, `_additionalQueryParams()`, and `_additionalBodyProperties()` methods. You can also set undocumented parameters on nested headers, query params, or body classes using the `putAdditionalProperty` method. These properties can be accessed on the built object later using the `_additionalProperties()` method.
+These can be accessed on the built object later using the `_additionalHeaders()`, `_additionalQueryParams()`, and `_additionalBodyProperties()` methods.
 
-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/JsonValue.kt) object to its setter:
+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
 
 val params: CurrentTimeRetrieveParams = CurrentTimeRetrieveParams.builder().build()
 ```
 
+The most straightforward way to create a [`JsonValue`](onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/core/Values.kt) is using its `from(...)` method:
+
+```kotlin
+import org.onebusaway.core.JsonValue
+
+// Create primitive JSON values
+val nullValue: JsonValue = JsonValue.from(null)
+val booleanValue: JsonValue = JsonValue.from(true)
+val numberValue: JsonValue = JsonValue.from(42)
+val stringValue: JsonValue = JsonValue.from("Hello World!")
+
+// Create a JSON array value equivalent to `["Hello", "World"]`
+val arrayValue: JsonValue = JsonValue.from(listOf(
+  "Hello", "World"
+))
+
+// Create a JSON object value equivalent to `{ "a": 1, "b": 2 }`
+val objectValue: JsonValue = JsonValue.from(mapOf(
+  "a" to 1, "b" to 2
+))
+
+// Create an arbitrarily nested JSON equivalent to:
+// {
+//   "a": [1, 2],
+//   "b": [3, 4]
+// }
+val complexValue: JsonValue = JsonValue.from(mapOf(
+  "a" to listOf(
+    1, 2
+  ), "b" to listOf(
+    3, 4
+  )
+))
+```
+
 ### Response properties
 
 To access undocumented response properties, call the `_additionalProperties()` method:

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "org.onebusaway"
-    version = "0.1.0-alpha.67" // x-release-please-version
+    version = "0.1.0-alpha.68" // x-release-please-version
 }
 
 subprojects {

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

@@ -22,11 +22,12 @@ configure<SpotlessExtension> {
 
 tasks.withType<KotlinCompile>().configureEach {
     compilerOptions {
+        allWarningsAsErrors = true
         freeCompilerArgs = listOf(
-          "-Xjvm-default=all",
-          "-Xjdk-release=1.8",
-          // Suppress deprecation warnings because we may still reference and test deprecated members.
-          "-Xsuppress-warning=DEPRECATION"
+            "-Xjvm-default=all",
+            "-Xjdk-release=1.8",
+            // Suppress deprecation warnings because we may still reference and test deprecated members.
+            "-Xsuppress-warning=DEPRECATION"
         )
         jvmTarget.set(JvmTarget.JVM_1_8)
     }

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/services/async/AgenciesWithCoverageServiceAsync.kt

@@ -24,10 +24,7 @@ interface AgenciesWithCoverageServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): AgenciesWithCoverageListResponse
 
-    /**
-     * Returns a list of all transit agencies currently supported by OneBusAway along with the
-     * center of their coverage area.
-     */
+    /** @see [list] */
     suspend fun list(requestOptions: RequestOptions): AgenciesWithCoverageListResponse =
         list(AgenciesWithCoverageListParams.none(), requestOptions)
 
@@ -47,10 +44,7 @@ interface AgenciesWithCoverageServiceAsync {
             requestOptions: RequestOptions = RequestOptions.none(),
         ): HttpResponseFor<AgenciesWithCoverageListResponse>
 
-        /**
-         * Returns a raw HTTP response for `get /api/where/agencies-with-coverage.json`, but is
-         * otherwise the same as [AgenciesWithCoverageServiceAsync.list].
-         */
+        /** @see [list] */
         @MustBeClosed
         suspend fun list(
             requestOptions: RequestOptions

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/services/async/ConfigServiceAsync.kt

@@ -21,7 +21,7 @@ interface ConfigServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): ConfigRetrieveResponse
 
-    /** config */
+    /** @see [retrieve] */
     suspend fun retrieve(requestOptions: RequestOptions): ConfigRetrieveResponse =
         retrieve(ConfigRetrieveParams.none(), requestOptions)
 
@@ -40,10 +40,7 @@ interface ConfigServiceAsync {
             requestOptions: RequestOptions = RequestOptions.none(),
         ): HttpResponseFor<ConfigRetrieveResponse>
 
-        /**
-         * Returns a raw HTTP response for `get /api/where/config.json`, but is otherwise the same
-         * as [ConfigServiceAsync.retrieve].
-         */
+        /** @see [retrieve] */
         @MustBeClosed
         suspend fun retrieve(
             requestOptions: RequestOptions

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/services/async/CurrentTimeServiceAsync.kt

@@ -21,7 +21,7 @@ interface CurrentTimeServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): CurrentTimeRetrieveResponse
 
-    /** current-time */
+    /** @see [retrieve] */
     suspend fun retrieve(requestOptions: RequestOptions): CurrentTimeRetrieveResponse =
         retrieve(CurrentTimeRetrieveParams.none(), requestOptions)
 
@@ -41,10 +41,7 @@ interface CurrentTimeServiceAsync {
             requestOptions: RequestOptions = RequestOptions.none(),
         ): HttpResponseFor<CurrentTimeRetrieveResponse>
 
-        /**
-         * Returns a raw HTTP response for `get /api/where/current-time.json`, but is otherwise the
-         * same as [CurrentTimeServiceAsync.retrieve].
-         */
+        /** @see [retrieve] */
         @MustBeClosed
         suspend fun retrieve(
             requestOptions: RequestOptions

onebusaway-sdk-kotlin-core/src/main/kotlin/org/onebusaway/services/blocking/AgenciesWithCoverageService.kt

@@ -24,10 +24,7 @@ interface AgenciesWithCoverageService {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): AgenciesWithCoverageListResponse
 
-    /**
-     * Returns a list of all transit agencies currently supported by OneBusAway along with the
-     * center of their coverage area.
-     */
+    /** @see [list] */
     fun list(requestOptions: RequestOptions): AgenciesWithCoverageListResponse =
         list(AgenciesWithCoverageListParams.none(), requestOptions)
 
@@ -47,10 +44,7 @@ interface AgenciesWithCoverageService {
             requestOptions: RequestOptions = RequestOptions.none(),
         ): HttpResponseFor<AgenciesWithCoverageListResponse>
 
-        /**
-         * Returns a raw HTTP response for `get /api/where/agencies-with-coverage.json`, but is
-         * otherwise the same as [AgenciesWithCoverageService.list].
-         */
+        /** @see [list] */
         @MustBeClosed
         fun list(
             requestOptions: RequestOptions