@ir-kit/kit 0.0.1 → 1.0.0

package/runtime/kotlin/Auth.kt

@@ -0,0 +1,86 @@
+package dev.irkit.runtime
+
+import okhttp3.HttpUrl
+import okhttp3.Request
+import java.util.Base64
+
+/**
+ * Auth schemes consumers reach for in practice:
+ *
+ *  - `Bearer(token)`            — `Authorization: Bearer <token>`.
+ *  - `ApiKey(name, value, in)`  — header / query / cookie placement,
+ *                                  matching the spec's
+ *                                  `securitySchemes.<name>.in`.
+ *  - `Basic(username, password)` — `Authorization: Basic <base64>`.
+ *
+ * Per-operation auth is auto-wired by the generator when an op has
+ * `security` requirements; it walks the requirement names and applies
+ * any matching scheme value the consumer has placed on `APIClient.auth`.
+ *
+ * `apply` mutates the request builder in-place for header / cookie
+ * auth and returns the (possibly rewritten) `HttpUrl` so query auth
+ * can re-thread its name=value into the URL.
+ */
+public sealed class Auth {
+    public abstract fun apply(
+        builder: Request.Builder,
+        url: HttpUrl,
+    ): HttpUrl
+
+    public data class Bearer(
+        public val token: String,
+    ) : Auth() {
+        override fun apply(
+            builder: Request.Builder,
+            url: HttpUrl,
+        ): HttpUrl {
+            builder.header("Authorization", "Bearer $token")
+            return url
+        }
+    }
+
+    public data class ApiKey(
+        public val name: String,
+        public val value: String,
+        public val location: APIKeyLocation,
+    ) : Auth() {
+        override fun apply(
+            builder: Request.Builder,
+            url: HttpUrl,
+        ): HttpUrl =
+            when (location) {
+                APIKeyLocation.HEADER -> {
+                    builder.header(name, value)
+                    url
+                }
+
+                APIKeyLocation.QUERY -> {
+                    url.newBuilder().addQueryParameter(name, value).build()
+                }
+
+                APIKeyLocation.COOKIE -> {
+                    val cookie = "$name=$value"
+                    val existing = builder.build().header("Cookie")
+                    builder.header("Cookie", existing?.let { "$it; $cookie" } ?: cookie)
+                    url
+                }
+            }
+    }
+
+    public data class Basic(
+        public val username: String,
+        public val password: String,
+    ) : Auth() {
+        override fun apply(
+            builder: Request.Builder,
+            url: HttpUrl,
+        ): HttpUrl {
+            val encoded =
+                Base64
+                    .getEncoder()
+                    .encodeToString("$username:$password".toByteArray(Charsets.UTF_8))
+            builder.header("Authorization", "Basic $encoded")
+            return url
+        }
+    }
+}

package/runtime/kotlin/MultipartFormBody.kt

@@ -0,0 +1,41 @@
+package dev.irkit.runtime
+
+import okhttp3.MediaType.Companion.toMediaTypeOrNull
+import okhttp3.MultipartBody
+import okhttp3.RequestBody
+import okhttp3.RequestBody.Companion.toRequestBody
+
+/**
+ * Thin wrapper over OkHttp's `MultipartBody.Builder` — keeps the impl
+ * code symmetric with the JSON / form-urlencoded paths.
+ *
+ *  - `appendText(name, value)`           — text part.
+ *  - `appendFile(name, filename, bytes,`
+ *    `mimeType)`                          — binary part.
+ *  - `build()`                            — finalizes and returns a
+ *                                            `RequestBody` ready to pass
+ *                                            into `.method("POST", body)`.
+ */
+public class MultipartFormBody {
+    private val builder: MultipartBody.Builder =
+        MultipartBody.Builder().setType(MultipartBody.FORM)
+
+    public fun appendText(
+        name: String,
+        value: String,
+    ) {
+        builder.addFormDataPart(name, value)
+    }
+
+    public fun appendFile(
+        name: String,
+        filename: String,
+        bytes: ByteArray,
+        mimeType: String = "application/octet-stream",
+    ) {
+        val body: RequestBody = bytes.toRequestBody(mimeType.toMediaTypeOrNull())
+        builder.addFormDataPart(name, filename, body)
+    }
+
+    public fun build(): RequestBody = builder.build()
+}

package/runtime/kotlin/QueryStyle.kt

@@ -0,0 +1,12 @@
+package dev.irkit.runtime
+
+/**
+ * Query-array serialization style — matches the OpenAPI 3 `style` field
+ * for query parameters whose value is an array. The default is `form`
+ * with explode=true; the others appear when the spec opts into them.
+ */
+public enum class QueryStyle {
+    FORM,
+    SPACE_DELIMITED,
+    PIPE_DELIMITED,
+}

package/runtime/kotlin/RequestOptions.kt

@@ -0,0 +1,29 @@
+package dev.irkit.runtime
+
+import okhttp3.HttpUrl
+import okhttp3.Request
+import okhttp3.Response
+
+/**
+ * Per-call options bag — every generated method takes a
+ * `RequestOptions` last param. Mirrors hey-api's TS SDK options shape.
+ *
+ *  - `client`               — override the impl's bound `APIClient`.
+ *  - `baseUrl`              — override `client.baseUrl` for one call.
+ *  - `timeout`              — per-call call-timeout in milliseconds.
+ *  - `headers`              — extra/override headers, applied last.
+ *  - `requestInterceptors`  — extra suspend interceptors, run after
+ *                              client-level ones.
+ *  - `responseValidator`    — runs after a 2xx response; throwing
+ *                              converts the call into an exception.
+ *  - `responseTransformer`  — rewrite the response body before decode.
+ */
+public data class RequestOptions(
+    public val client: APIClient? = null,
+    public val baseUrl: HttpUrl? = null,
+    public val timeout: Long? = null,
+    public val headers: Map<String, String> = emptyMap(),
+    public val requestInterceptors: List<suspend (Request) -> Request> = emptyList(),
+    public val responseValidator: (suspend (ByteArray, Response) -> Unit)? = null,
+    public val responseTransformer: (suspend (ByteArray) -> ByteArray)? = null,
+)

package/runtime/kotlin/URLEncoding.kt

@@ -0,0 +1,45 @@
+package dev.irkit.runtime
+
+import okhttp3.HttpUrl
+
+/**
+ * Helpers used by generated impl code to add OpenAPI-shaped query
+ * parameters onto an `HttpUrl.Builder` without each call site having to
+ * know the style/explode rules.
+ *
+ *  - `addScalar` skips when the value is `null` so optional-and-missing
+ *    params don't emit a key at all.
+ *  - `addArray` honours `style` + `explode`: explode=true emits one
+ *    `?name=v` per element; explode=false joins per the style separator.
+ */
+public object URLEncoding {
+    public fun addScalar(
+        builder: HttpUrl.Builder,
+        name: String,
+        value: Any?,
+    ) {
+        if (value == null) return
+        builder.addQueryParameter(name, value.toString())
+    }
+
+    public fun addArray(
+        builder: HttpUrl.Builder,
+        name: String,
+        values: List<Any>?,
+        style: QueryStyle = QueryStyle.FORM,
+        explode: Boolean = true,
+    ) {
+        if (values == null) return
+        if (explode) {
+            for (v in values) builder.addQueryParameter(name, v.toString())
+            return
+        }
+        val sep =
+            when (style) {
+                QueryStyle.FORM -> ","
+                QueryStyle.SPACE_DELIMITED -> " "
+                QueryStyle.PIPE_DELIMITED -> "|"
+            }
+        builder.addQueryParameter(name, values.joinToString(sep) { it.toString() })
+    }
+}