refactor(client): deduplicate page response classes (#401)

feat(client): make pagination robust to missing data
docs: add comments for page methods

Author: stainless-app[bot]

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertListPage.kt

@@ -2,17 +2,7 @@
 
 package com.withorb.api.models
 
-import com.fasterxml.jackson.annotation.JsonAnyGetter
-import com.fasterxml.jackson.annotation.JsonAnySetter
-import com.fasterxml.jackson.annotation.JsonCreator
-import com.fasterxml.jackson.annotation.JsonProperty
-import com.withorb.api.core.ExcludeMissing
-import com.withorb.api.core.JsonField
-import com.withorb.api.core.JsonMissing
-import com.withorb.api.core.JsonValue
-import com.withorb.api.errors.OrbInvalidDataException
 import com.withorb.api.services.blocking.AlertService
-import java.util.Collections
 import java.util.Objects
 import java.util.Optional
 import java.util.stream.Stream
@@ -34,14 +24,26 @@ class AlertListPage
 private constructor(
     private val alertsService: AlertService,
     private val params: AlertListParams,
-    private val response: Response,
+    private val response: AlertListPageResponse,
 ) {
 
-    fun response(): Response = response
+    /** Returns the response that this page was parsed from. */
+    fun response(): AlertListPageResponse = response
 
-    fun data(): List<Alert> = response().data()
+    /**
+     * Delegates to [AlertListPageResponse], but gracefully handles missing data.
+     *
+     * @see [AlertListPageResponse.data]
+     */
+    fun data(): List<Alert> = response._data().getOptional("data").getOrNull() ?: emptyList()
 
-    fun paginationMetadata(): PaginationMetadata = response().paginationMetadata()
+    /**
+     * Delegates to [AlertListPageResponse], but gracefully handles missing data.
+     *
+     * @see [AlertListPageResponse.paginationMetadata]
+     */
+    fun paginationMetadata(): Optional<PaginationMetadata> =
+        response._paginationMetadata().getOptional("pagination_metadata")
 
     override fun equals(other: Any?): Boolean {
         if (this === other) {
@@ -56,23 +58,23 @@ private constructor(
     override fun toString() =
         "AlertListPage{alertsService=$alertsService, params=$params, response=$response}"
 
-    fun hasNextPage(): Boolean {
-        if (data().isEmpty()) {
-            return false
-        }
-
-        return paginationMetadata().nextCursor().isPresent
-    }
+    fun hasNextPage(): Boolean =
+        data().isNotEmpty() &&
+            paginationMetadata().flatMap { it._nextCursor().getOptional("next_cursor") }.isPresent
 
     fun getNextPageParams(): Optional<AlertListParams> {
         if (!hasNextPage()) {
             return Optional.empty()
         }
 
         return Optional.of(
-            AlertListParams.builder()
-                .from(params)
-                .apply { paginationMetadata().nextCursor().ifPresent { this.cursor(it) } }
+            params
+                .toBuilder()
+                .apply {
+                    paginationMetadata()
+                        .flatMap { it._nextCursor().getOptional("next_cursor") }
+                        .ifPresent { cursor(it) }
+                }
                 .build()
         )
     }
@@ -86,122 +88,11 @@ private constructor(
     companion object {
 
         @JvmStatic
-        fun of(alertsService: AlertService, params: AlertListParams, response: Response) =
-            AlertListPage(alertsService, params, response)
-    }
-
-    class Response(
-        private val data: JsonField<List<Alert>>,
-        private val paginationMetadata: JsonField<PaginationMetadata>,
-        private val additionalProperties: MutableMap<String, JsonValue>,
-    ) {
-
-        @JsonCreator
-        private constructor(
-            @JsonProperty("data") data: JsonField<List<Alert>> = JsonMissing.of(),
-            @JsonProperty("pagination_metadata")
-            paginationMetadata: JsonField<PaginationMetadata> = JsonMissing.of(),
-        ) : this(data, paginationMetadata, mutableMapOf())
-
-        fun data(): List<Alert> = data.getOptional("data").getOrNull() ?: listOf()
-
-        fun paginationMetadata(): PaginationMetadata =
-            paginationMetadata.getRequired("pagination_metadata")
-
-        @JsonProperty("data")
-        fun _data(): Optional<JsonField<List<Alert>>> = Optional.ofNullable(data)
-
-        @JsonProperty("pagination_metadata")
-        fun _paginationMetadata(): Optional<JsonField<PaginationMetadata>> =
-            Optional.ofNullable(paginationMetadata)
-
-        @JsonAnySetter
-        private fun putAdditionalProperty(key: String, value: JsonValue) {
-            additionalProperties.put(key, value)
-        }
-
-        @JsonAnyGetter
-        @ExcludeMissing
-        fun _additionalProperties(): Map<String, JsonValue> =
-            Collections.unmodifiableMap(additionalProperties)
-
-        private var validated: Boolean = false
-
-        fun validate(): Response = apply {
-            if (validated) {
-                return@apply
-            }
-
-            data().map { it.validate() }
-            paginationMetadata().validate()
-            validated = true
-        }
-
-        fun isValid(): Boolean =
-            try {
-                validate()
-                true
-            } catch (e: OrbInvalidDataException) {
-                false
-            }
-
-        fun toBuilder() = Builder().from(this)
-
-        override fun equals(other: Any?): Boolean {
-            if (this === other) {
-                return true
-            }
-
-            return /* spotless:off */ other is Response && data == other.data && paginationMetadata == other.paginationMetadata && additionalProperties == other.additionalProperties /* spotless:on */
-        }
-
-        override fun hashCode(): Int = /* spotless:off */ Objects.hash(data, paginationMetadata, additionalProperties) /* spotless:on */
-
-        override fun toString() =
-            "Response{data=$data, paginationMetadata=$paginationMetadata, additionalProperties=$additionalProperties}"
-
-        companion object {
-
-            /** Returns a mutable builder for constructing an instance of [AlertListPage]. */
-            @JvmStatic fun builder() = Builder()
-        }
-
-        class Builder {
-
-            private var data: JsonField<List<Alert>> = JsonMissing.of()
-            private var paginationMetadata: JsonField<PaginationMetadata> = JsonMissing.of()
-            private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
-
-            @JvmSynthetic
-            internal fun from(page: Response) = apply {
-                this.data = page.data
-                this.paginationMetadata = page.paginationMetadata
-                this.additionalProperties.putAll(page.additionalProperties)
-            }
-
-            fun data(data: List<Alert>) = data(JsonField.of(data))
-
-            fun data(data: JsonField<List<Alert>>) = apply { this.data = data }
-
-            fun paginationMetadata(paginationMetadata: PaginationMetadata) =
-                paginationMetadata(JsonField.of(paginationMetadata))
-
-            fun paginationMetadata(paginationMetadata: JsonField<PaginationMetadata>) = apply {
-                this.paginationMetadata = paginationMetadata
-            }
-
-            fun putAdditionalProperty(key: String, value: JsonValue) = apply {
-                this.additionalProperties.put(key, value)
-            }
-
-            /**
-             * Returns an immutable instance of [Response].
-             *
-             * Further updates to this [Builder] will not mutate the returned instance.
-             */
-            fun build(): Response =
-                Response(data, paginationMetadata, additionalProperties.toMutableMap())
-        }
+        fun of(
+            alertsService: AlertService,
+            params: AlertListParams,
+            response: AlertListPageResponse,
+        ) = AlertListPage(alertsService, params, response)
     }
 
     class AutoPager(private val firstPage: AlertListPage) : Iterable<Alert> {