kotlin: Replace most query param classes with generated ones (#1587)

svix-jplatte · web-flow · commit 2dc19a950322 · 2024-12-23T18:33:42.000+01:00
… and clean up the remaining ones to prepare for future replacement. Also leave the default for the `limit` on pagination APIs up to the server. I don't think we need to mention this in the changelog since so far the default has been the same as on the server side; however if we were to change the limit for some API on the server side, it makes much more sense to me that the new default would apply immediately and for everyone who doesn't specify it, rather than requiring a libs update for Kotlin users. Part of svix/monorepo-private#9576.
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -9,13 +9,16 @@
   `MessageAttempt.listAttemptedDestinations` ([#1571])
 * Libs/JavaScript **(Breaking)**: Rename `EndpointStatsOptions` interface to
   `EndpointGetStatsOptions` ([#1585])
+* Libs/Kotlin **(Breaking)**: Remove `ListOptions` class. Usage of classes that were inheriting
+  from it should not change though ([#1587])
 * Libs/Rust: Add `api::Authentication::expire_all` ([#1584])
 * Libs/Rust: Rename some `Options` types. The old names remain as deprecated type aliases ([#1584])
 
 [#1568]: https://github.com/svix/svix-webhooks/pull/1568
 [#1571]: https://github.com/svix/svix-webhooks/pull/1571
 [#1584]: https://github.com/svix/svix-webhooks/pull/1584
 [#1585]: https://github.com/svix/svix-webhooks/pull/1585
+[#1587]: https://github.com/svix/svix-webhooks/pull/1587
 
 ## Version 1.44.0
 * Libs/JavaScript: Revert packaging-related change because it broke for some users ([#1556])
diff --git a/kotlin/lib/src/main/kotlin/Application.kt b/kotlin/lib/src/main/kotlin/Application.kt
@@ -8,16 +8,19 @@ import com.svix.kotlin.models.ApplicationPatch
 import com.svix.kotlin.models.ListResponseApplicationOut
 import com.svix.kotlin.models.Ordering
 
-class ApplicationListOptions : ListOptions() {
+class ApplicationListOptions {
+    var limit: Int? = null
+    var iterator: String? = null
     var order: Ordering? = null
 
-    fun order(order: Ordering) = apply { this.order = order }
+    /** Limit the number of returned items */
+    fun limit(limit: Int) = apply { this.limit = limit }
 
-    override fun iterator(iterator: String): ApplicationListOptions = apply {
-        super.iterator(iterator)
-    }
+    /** The iterator returned from a prior invocation */
+    fun iterator(iterator: String) = apply { this.iterator = iterator }
 
-    override fun limit(limit: Int) = apply { super.limit(limit) }
+    /** The sorting order of the returned items */
+    fun order(order: Ordering) = apply { this.order = order }
 }
 
 class Application internal constructor(token: String, options: SvixOptions) {
diff --git a/kotlin/lib/src/main/kotlin/BackgroundTask.kt b/kotlin/lib/src/main/kotlin/BackgroundTask.kt
@@ -8,7 +8,9 @@ import com.svix.kotlin.models.BackgroundTaskType
 import com.svix.kotlin.models.ListResponseBackgroundTaskOut
 import com.svix.kotlin.models.Ordering
 
-class BackgroundTaskListOptions : ListOptions() {
+class BackgroundTaskListOptions {
+    var iterator: String? = null
+    var limit: Int? = null
     var status: BackgroundTaskStatus? = null
     var task: BackgroundTaskType? = null
     var order: Ordering? = null
@@ -19,9 +21,9 @@ class BackgroundTaskListOptions : ListOptions() {
 
     fun task(task: BackgroundTaskType) = apply { this.task = task }
 
-    override fun iterator(iterator: String) = apply { super.iterator(iterator) }
+    fun iterator(iterator: String) = apply { this.iterator = iterator }
 
-    override fun limit(limit: Int) = apply { super.limit(limit) }
+    fun limit(limit: Int) = apply { this.limit = limit }
 }
 
 class BackgroundTask internal constructor(token: String, options: SvixOptions) {
diff --git a/kotlin/lib/src/main/kotlin/Endpoint.kt b/kotlin/lib/src/main/kotlin/Endpoint.kt
@@ -21,19 +21,30 @@ import com.svix.kotlin.models.RecoverIn
 import com.svix.kotlin.models.ReplayIn
 import java.time.OffsetDateTime
 
-class EndpointListOptions : ListOptions() {
+class EndpointListOptions {
+    var limit: Int? = null
+    var iterator: String? = null
     var order: Ordering? = null
 
-    fun order(order: Ordering) = apply { this.order = order }
+    /** Limit the number of returned items */
+    fun limit(limit: Int) = apply { this.limit = limit }
 
-    override fun iterator(iterator: String) = apply { super.iterator(iterator) }
+    /** The iterator returned from a prior invocation */
+    fun iterator(iterator: String) = apply { this.iterator = iterator }
 
-    override fun limit(limit: Int) = apply { super.limit(limit) }
+    /** The sorting order of the returned items */
+    fun order(order: Ordering) = apply { this.order = order }
 }
 
-class EndpointStatsOptions {
+class EndpointGetStatsOptions {
     var since: OffsetDateTime? = null
     var until: OffsetDateTime? = null
+
+    /** Filter the range to data starting from this date. */
+    fun since(since: OffsetDateTime) = apply { this.since = since }
+
+    /** Filter the range to data ending by this date. */
+    fun until(until: OffsetDateTime) = apply { this.until = until }
 }
 
 class Endpoint internal constructor(token: String, options: SvixOptions) {
@@ -183,7 +194,7 @@ class Endpoint internal constructor(token: String, options: SvixOptions) {
     suspend fun getStats(
         appId: String,
         endpointId: String,
-        options: EndpointStatsOptions = EndpointStatsOptions(),
+        options: EndpointGetStatsOptions = EndpointGetStatsOptions(),
     ): EndpointStats {
         try {
             return api.v1EndpointGetStats(appId, endpointId, options.since, options.until)
diff --git a/kotlin/lib/src/main/kotlin/EventType.kt b/kotlin/lib/src/main/kotlin/EventType.kt
@@ -9,18 +9,32 @@ import com.svix.kotlin.models.EventTypeOut
 import com.svix.kotlin.models.EventTypePatch
 import com.svix.kotlin.models.EventTypeUpdate
 import com.svix.kotlin.models.ListResponseEventTypeOut
+import com.svix.kotlin.models.Ordering
 
-class EventTypeListOptions() : ListOptions() {
+class EventTypeListOptions {
+    var limit: Int? = null
+    var iterator: String? = null
+    var order: Ordering? = null
+    var includeArchived: Boolean? = null
     var withContent: Boolean? = null
-    var includeAchived: Boolean? = null
 
-    fun withContent(withContent: Boolean) = apply { this.withContent = withContent }
+    /** Limit the number of returned items */
+    fun limit(limit: Int) = apply { this.limit = limit }
+
+    /** The iterator returned from a prior invocation */
+    fun iterator(iterator: String) = apply { this.iterator = iterator }
 
-    fun includeAchived(includeAchived: Boolean) = apply { this.includeAchived = includeAchived }
+    /** The sorting order of the returned items */
+    fun order(order: Ordering) = apply { this.order = order }
 
-    override fun iterator(iterator: String) = apply { super.iterator(iterator) }
+    /** When `true` archived (deleted but not expunged) items are included in the response. */
+    fun includeArchived(includeArchived: Boolean) = apply { this.includeArchived = includeArchived }
 
-    override fun limit(limit: Int) = apply { super.limit(limit) }
+    @Deprecated("Use the new includeArchived() method")
+    fun includeAchived(includeArchived: Boolean) = apply { this.includeArchived = includeArchived }
+
+    /** When `true` the full item (including the schema) is included in the response. */
+    fun withContent(withContent: Boolean) = apply { this.withContent = withContent }
 }
 
 class EventType internal constructor(token: String, options: SvixOptions) {
@@ -41,7 +55,7 @@ class EventType internal constructor(token: String, options: SvixOptions) {
                 options.limit,
                 options.iterator,
                 null,
-                options.includeAchived,
+                options.includeArchived,
                 options.withContent,
             )
         } catch (e: Exception) {
diff --git a/kotlin/lib/src/main/kotlin/Integration.kt b/kotlin/lib/src/main/kotlin/Integration.kt
@@ -9,13 +9,18 @@ import com.svix.kotlin.models.IntegrationUpdate
 import com.svix.kotlin.models.ListResponseIntegrationOut
 import com.svix.kotlin.models.Ordering
 
-class IntegrationListOptions : ListOptions() {
+class IntegrationListOptions {
+    var limit: Int? = null
+    var iterator: String? = null
     var order: Ordering? = null
 
-    override fun iterator(iterator: String) = apply { super.iterator(iterator) }
+    /** Limit the number of returned items */
+    fun limit(limit: Int) = apply { this.limit = limit }
 
-    override fun limit(limit: Int) = apply { super.limit(limit) }
+    /** The iterator returned from a prior invocation */
+    fun iterator(iterator: String) = apply { this.iterator = iterator }
 
+    /** The sorting order of the returned items */
     fun order(order: Ordering) = apply { this.order = order }
 }
 
diff --git a/kotlin/lib/src/main/kotlin/ListOptions.kt b/kotlin/lib/src/main/kotlin/ListOptions.kt
diff --git a/kotlin/lib/src/main/kotlin/Message.kt b/kotlin/lib/src/main/kotlin/Message.kt
@@ -8,29 +8,39 @@ import com.svix.kotlin.models.MessageIn
 import com.svix.kotlin.models.MessageOut
 import java.time.OffsetDateTime
 
-class MessageListOptions : ListOptions() {
-    var eventTypes: List<String>? = null
+class MessageListOptions {
+    var limit: Int? = null
+    var iterator: String? = null
+    var channel: String? = null
     var before: OffsetDateTime? = null
     var after: OffsetDateTime? = null
-    var channel: String? = null
     var withContent: Boolean? = null
     var tag: String? = null
+    var eventTypes: List<String>? = null
 
-    fun eventTypes(eventTypes: List<String>) = apply { this.eventTypes = eventTypes }
-
-    fun before(before: OffsetDateTime) = apply { this.before = before }
+    /** Limit the number of returned items */
+    fun limit(limit: Int) = apply { this.limit = limit }
 
-    fun after(after: OffsetDateTime) = apply { this.after = after }
+    /** The iterator returned from a prior invocation */
+    fun iterator(iterator: String) = apply { this.iterator = iterator }
 
+    /** Filter response based on the channel. */
     fun channel(channel: String) = apply { this.channel = channel }
 
-    override fun iterator(iterator: String) = apply { super.iterator(iterator) }
+    /** Only include items created before a certain date. */
+    fun before(before: OffsetDateTime) = apply { this.before = before }
 
-    override fun limit(limit: Int) = apply { super.limit(limit) }
+    /** Only include items created after a certain date. */
+    fun after(after: OffsetDateTime) = apply { this.after = after }
 
+    /** When `true` message payloads are included in the response. */
     fun withContent(withContent: Boolean) = apply { this.withContent = withContent }
 
+    /** Filter messages matching the provided tag. */
     fun tag(tag: String) = apply { this.tag = tag }
+
+    /** Filter response based on the event type */
+    fun eventTypes(eventTypes: List<String>) = apply { this.eventTypes = eventTypes }
 }
 
 class Message internal constructor(token: String, options: SvixOptions) {
diff --git a/kotlin/lib/src/main/kotlin/MessageAttempt.kt b/kotlin/lib/src/main/kotlin/MessageAttempt.kt
@@ -12,6 +12,8 @@ import com.svix.kotlin.models.StatusCodeClass
 import java.time.OffsetDateTime
 
 class MessageAttemptListOptions(
+    var iterator: String? = null,
+    var limit: Int? = null,
     var messageStatus: MessageStatus? = null,
     var before: OffsetDateTime? = null,
     var after: OffsetDateTime? = null,
@@ -22,7 +24,7 @@ class MessageAttemptListOptions(
     var endpointId: String? = null,
     var withContent: Boolean? = null,
     var withMsg: Boolean? = null,
-) : ListOptions() {
+) {
     fun messageStatus(messageStatus: MessageStatus) = apply { this.messageStatus = messageStatus }
 
     fun before(before: OffsetDateTime) = apply { this.before = before }
@@ -37,9 +39,9 @@ class MessageAttemptListOptions(
 
     fun channel(channel: String) = apply { this.channel = channel }
 
-    override fun iterator(iterator: String) = apply { super.iterator(iterator) }
+    fun iterator(iterator: String) = apply { this.iterator = iterator }
 
-    override fun limit(limit: Int) = apply { super.limit(limit) }
+    fun limit(limit: Int) = apply { this.limit = limit }
 
     fun endpointId(endpointId: String) = apply { this.endpointId = endpointId }
 
diff --git a/kotlin/lib/src/main/kotlin/OperationalWebhookEndpoint.kt b/kotlin/lib/src/main/kotlin/OperationalWebhookEndpoint.kt
@@ -10,14 +10,19 @@ import com.svix.kotlin.models.OperationalWebhookEndpointSecretOut
 import com.svix.kotlin.models.OperationalWebhookEndpointUpdate
 import com.svix.kotlin.models.Ordering
 
-class OperationalWebhookEndpointListOptions : ListOptions() {
+class OperationalWebhookEndpointListOptions {
+    var limit: Int? = null
+    var iterator: String? = null
     var order: Ordering? = null
 
-    fun order(order: Ordering) = apply { this.order = order }
+    /** Limit the number of returned items */
+    fun limit(limit: Int) = apply { this.limit = limit }
 
-    override fun iterator(iterator: String) = apply { super.iterator(iterator) }
+    /** The iterator returned from a prior invocation */
+    fun iterator(iterator: String) = apply { this.iterator = iterator }
 
-    override fun limit(limit: Int) = apply { super.limit(limit) }
+    /** The sorting order of the returned items */
+    fun order(order: Ordering) = apply { this.order = order }
 }
 
 class OperationalWebhookEndpoint internal constructor(token: String, options: SvixOptions) {
