feat: expose immutable Headers map view

openai-java-core/src/main/kotlin/com/openai/core/http/Headers.kt

@@ -21,8 +21,21 @@ private constructor(
 
     fun names(): Set<String> = map.keys
 
+    /**
+     * Returns all values associated with [name], or an empty list when the header is absent.
+     *
+     * Names returned by [names] always have at least one value.
+     */
     fun values(name: String): List<String> = map[name].orEmpty()
 
+    /**
+     * Returns the immutable, case-insensitive mapping of header names to their values.
+     *
+     * The returned map and its value lists are the same immutable representation used by this
+     * [Headers] instance; mutating the returned data is not supported.
+     */
+    fun asMap(): Map<String, List<String>> = map
+
     fun toBuilder(): Builder = Builder().putAll(map)
 
     companion object {

openai-java-core/src/test/kotlin/com/openai/core/http/HeadersMapViewTest.kt

@@ -0,0 +1,46 @@
+package com.openai.core.http
+
+import org.assertj.core.api.Assertions.assertThat
+import org.assertj.core.api.Assertions.assertThatThrownBy
+import org.junit.jupiter.api.Test
+
+internal class HeadersMapViewTest {
+
+    @Test
+    fun asMapReturnsCaseInsensitiveImmutableHeaderMapping() {
+        val headers =
+            Headers.builder()
+                .put("X-Test", "one")
+                .put("x-test", "two")
+                .put("Other", "value")
+                .build()
+
+        val map = headers.asMap()
+
+        assertThat(map["X-TEST"]).containsExactly("one", "two")
+        assertThat(map["other"]).containsExactly("value")
+        assertThat(map).hasSize(2)
+    }
+
+    @Test
+    fun asMapDoesNotAllowMapMutation() {
+        val map = Headers.builder().put("X-Test", "value").build().asMap()
+
+        assertThatThrownBy {
+                @Suppress("UNCHECKED_CAST")
+                (map as MutableMap<String, List<String>>)["Other"] = listOf("value")
+            }
+            .isInstanceOf(UnsupportedOperationException::class.java)
+    }
+
+    @Test
+    fun asMapDoesNotAllowValueListMutation() {
+        val values = Headers.builder().put("X-Test", "value").build().asMap()["X-Test"]!!
+
+        assertThatThrownBy {
+                @Suppress("UNCHECKED_CAST")
+                (values as MutableList<String>).add("other")
+            }
+            .isInstanceOf(UnsupportedOperationException::class.java)
+    }
+}