feat(client): allow providing some params positionally

Author: stainless-app[bot]

README.md

@@ -188,10 +188,7 @@ import app.knock.api.core.http.HttpResponseFor;
 import app.knock.api.models.users.User;
 import app.knock.api.models.users.UserGetParams;
 
-UserGetParams params = UserGetParams.builder()
-    .userId("dnedry")
-    .build();
-HttpResponseFor<User> user = client.users().withRawResponse().get(params);
+HttpResponseFor<User> user = client.users().withRawResponse().get("dnedry");
 
 int statusCode = user.statusCode();
 Headers headers = user.headers();
@@ -463,7 +460,6 @@ import app.knock.api.core.JsonValue;
 import app.knock.api.models.workflows.WorkflowTriggerParams;
 
 WorkflowTriggerParams params = WorkflowTriggerParams.builder()
-    .key("dinosaurs-loose")
     .recipients(JsonValue.from(42))
     .data(WorkflowTriggerParams.Data.builder()
         .putAdditionalProperty("dinosaur", JsonValue.from("triceratops"))

knock-java-core/src/main/kotlin/app/knock/api/core/Check.kt

@@ -5,6 +5,9 @@ package app.knock.api.core
 import com.fasterxml.jackson.core.Version
 import com.fasterxml.jackson.core.util.VersionUtil
 
+fun checkRequired(name: String, condition: Boolean) =
+    check(condition) { "`$name` is required, but was not set" }
+
 fun <T : Any> checkRequired(name: String, value: T?): T =
     checkNotNull(value) { "`$name` is required, but was not set" }
 

knock-java-core/src/main/kotlin/app/knock/api/models/audiences/AudienceAddMembersParams.kt

@@ -25,13 +25,13 @@ import kotlin.jvm.optionals.getOrNull
 /** Adds one or more members to the specified audience. */
 class AudienceAddMembersParams
 private constructor(
-    private val key: String,
+    private val key: String?,
     private val body: Body,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
 ) : Params {
 
-    fun key(): String = key
+    fun key(): Optional<String> = Optional.ofNullable(key)
 
     /**
      * A list of audience members to add.
@@ -63,7 +63,6 @@ private constructor(
          *
          * The following fields are required:
          * ```java
-         * .key()
          * .members()
          * ```
          */
@@ -86,7 +85,10 @@ private constructor(
             additionalQueryParams = audienceAddMembersParams.additionalQueryParams.toBuilder()
         }
 
-        fun key(key: String) = apply { this.key = key }
+        fun key(key: String?) = apply { this.key = key }
+
+        /** Alias for calling [Builder.key] with `key.orElse(null)`. */
+        fun key(key: Optional<String>) = key(key.getOrNull())
 
         /**
          * Sets the entire request body.
@@ -240,15 +242,14 @@ private constructor(
          *
          * The following fields are required:
          * ```java
-         * .key()
          * .members()
          * ```
          *
          * @throws IllegalStateException if any required field is unset.
          */
         fun build(): AudienceAddMembersParams =
             AudienceAddMembersParams(
-                checkRequired("key", key),
+                key,
                 body.build(),
                 additionalHeaders.build(),
                 additionalQueryParams.build(),
@@ -259,7 +260,7 @@ private constructor(
 
     fun _pathParam(index: Int): String =
         when (index) {
-            0 -> key
+            0 -> key ?: ""
             else -> ""
         }
 

knock-java-core/src/main/kotlin/app/knock/api/models/audiences/AudienceListMembersParams.kt

@@ -3,20 +3,21 @@
 package app.knock.api.models.audiences
 
 import app.knock.api.core.Params
-import app.knock.api.core.checkRequired
 import app.knock.api.core.http.Headers
 import app.knock.api.core.http.QueryParams
 import java.util.Objects
+import java.util.Optional
+import kotlin.jvm.optionals.getOrNull
 
 /** Returns a paginated list of members for the specified audience. */
 class AudienceListMembersParams
 private constructor(
-    private val key: String,
+    private val key: String?,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
 ) : Params {
 
-    fun key(): String = key
+    fun key(): Optional<String> = Optional.ofNullable(key)
 
     fun _additionalHeaders(): Headers = additionalHeaders
 
@@ -26,13 +27,10 @@ private constructor(
 
     companion object {
 
+        @JvmStatic fun none(): AudienceListMembersParams = builder().build()
+
         /**
          * Returns a mutable builder for constructing an instance of [AudienceListMembersParams].
-         *
-         * The following fields are required:
-         * ```java
-         * .key()
-         * ```
          */
         @JvmStatic fun builder() = Builder()
     }
@@ -51,7 +49,10 @@ private constructor(
             additionalQueryParams = audienceListMembersParams.additionalQueryParams.toBuilder()
         }
 
-        fun key(key: String) = apply { this.key = key }
+        fun key(key: String?) = apply { this.key = key }
+
+        /** Alias for calling [Builder.key] with `key.orElse(null)`. */
+        fun key(key: Optional<String>) = key(key.getOrNull())
 
         fun additionalHeaders(additionalHeaders: Headers) = apply {
             this.additionalHeaders.clear()
@@ -155,25 +156,14 @@ private constructor(
          * Returns an immutable instance of [AudienceListMembersParams].
          *
          * Further updates to this [Builder] will not mutate the returned instance.
-         *
-         * The following fields are required:
-         * ```java
-         * .key()
-         * ```
-         *
-         * @throws IllegalStateException if any required field is unset.
          */
         fun build(): AudienceListMembersParams =
-            AudienceListMembersParams(
-                checkRequired("key", key),
-                additionalHeaders.build(),
-                additionalQueryParams.build(),
-            )
+            AudienceListMembersParams(key, additionalHeaders.build(), additionalQueryParams.build())
     }
 
     fun _pathParam(index: Int): String =
         when (index) {
-            0 -> key
+            0 -> key ?: ""
             else -> ""
         }
 

knock-java-core/src/main/kotlin/app/knock/api/models/audiences/AudienceRemoveMembersParams.kt

@@ -25,13 +25,13 @@ import kotlin.jvm.optionals.getOrNull
 /** Removes one or more members from the specified audience. */
 class AudienceRemoveMembersParams
 private constructor(
-    private val key: String,
+    private val key: String?,
     private val body: Body,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
 ) : Params {
 
-    fun key(): String = key
+    fun key(): Optional<String> = Optional.ofNullable(key)
 
     /**
      * A list of audience members to remove.
@@ -63,7 +63,6 @@ private constructor(
          *
          * The following fields are required:
          * ```java
-         * .key()
          * .members()
          * ```
          */
@@ -86,7 +85,10 @@ private constructor(
             additionalQueryParams = audienceRemoveMembersParams.additionalQueryParams.toBuilder()
         }
 
-        fun key(key: String) = apply { this.key = key }
+        fun key(key: String?) = apply { this.key = key }
+
+        /** Alias for calling [Builder.key] with `key.orElse(null)`. */
+        fun key(key: Optional<String>) = key(key.getOrNull())
 
         /**
          * Sets the entire request body.
@@ -240,15 +242,14 @@ private constructor(
          *
          * The following fields are required:
          * ```java
-         * .key()
          * .members()
          * ```
          *
          * @throws IllegalStateException if any required field is unset.
          */
         fun build(): AudienceRemoveMembersParams =
             AudienceRemoveMembersParams(
-                checkRequired("key", key),
+                key,
                 body.build(),
                 additionalHeaders.build(),
                 additionalQueryParams.build(),
@@ -259,7 +260,7 @@ private constructor(
 
     fun _pathParam(index: Int): String =
         when (index) {
-            0 -> key
+            0 -> key ?: ""
             else -> ""
         }
 

knock-java-core/src/main/kotlin/app/knock/api/models/bulkoperations/BulkOperationGetParams.kt

@@ -3,20 +3,21 @@
 package app.knock.api.models.bulkoperations
 
 import app.knock.api.core.Params
-import app.knock.api.core.checkRequired
 import app.knock.api.core.http.Headers
 import app.knock.api.core.http.QueryParams
 import java.util.Objects
+import java.util.Optional
+import kotlin.jvm.optionals.getOrNull
 
 /** Retrieves a bulk operation (if it exists) and displays the current state of it. */
 class BulkOperationGetParams
 private constructor(
-    private val id: String,
+    private val id: String?,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
 ) : Params {
 
-    fun id(): String = id
+    fun id(): Optional<String> = Optional.ofNullable(id)
 
     fun _additionalHeaders(): Headers = additionalHeaders
 
@@ -26,14 +27,9 @@ private constructor(
 
     companion object {
 
-        /**
-         * Returns a mutable builder for constructing an instance of [BulkOperationGetParams].
-         *
-         * The following fields are required:
-         * ```java
-         * .id()
-         * ```
-         */
+        @JvmStatic fun none(): BulkOperationGetParams = builder().build()
+
+        /** Returns a mutable builder for constructing an instance of [BulkOperationGetParams]. */
         @JvmStatic fun builder() = Builder()
     }
 
@@ -51,7 +47,10 @@ private constructor(
             additionalQueryParams = bulkOperationGetParams.additionalQueryParams.toBuilder()
         }
 
-        fun id(id: String) = apply { this.id = id }
+        fun id(id: String?) = apply { this.id = id }
+
+        /** Alias for calling [Builder.id] with `id.orElse(null)`. */
+        fun id(id: Optional<String>) = id(id.getOrNull())
 
         fun additionalHeaders(additionalHeaders: Headers) = apply {
             this.additionalHeaders.clear()
@@ -155,25 +154,14 @@ private constructor(
          * Returns an immutable instance of [BulkOperationGetParams].
          *
          * Further updates to this [Builder] will not mutate the returned instance.
-         *
-         * The following fields are required:
-         * ```java
-         * .id()
-         * ```
-         *
-         * @throws IllegalStateException if any required field is unset.
          */
         fun build(): BulkOperationGetParams =
-            BulkOperationGetParams(
-                checkRequired("id", id),
-                additionalHeaders.build(),
-                additionalQueryParams.build(),
-            )
+            BulkOperationGetParams(id, additionalHeaders.build(), additionalQueryParams.build())
     }
 
     fun _pathParam(index: Int): String =
         when (index) {
-            0 -> id
+            0 -> id ?: ""
             else -> ""
         }