release: 3.1.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.0.0"
+  ".": "3.1.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 47
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-c7f578172392bde58bbb72be2a25b9e917529cd07550358c645ce155debf2418.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc/imagekit-362d0336e8f52ab1beb7d9602a3665dbb0277700e8dc01ef4f96fc7651699349.yml
 openapi_spec_hash: f0d797a17b1e8e81707517700cd44b13
-config_hash: da0c89d794fefcf600a4ddfc78553c2a
+config_hash: 94f48fd13b7d41b8b6a203a3a8cee9ed

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 3.1.0 (2026-05-06)
+
+Full Changelog: [v3.0.0...v3.1.0](https://github.com/imagekit-developer/imagekit-java/compare/v3.0.0...v3.1.0)
+
+### Features
+
+* **client:** improve logging ([a62b5e3](https://github.com/imagekit-developer/imagekit-java/commit/a62b5e30077bab50d3a9764daa7c520df18914bb))
+* **client:** more robust error parsing ([8e42517](https://github.com/imagekit-developer/imagekit-java/commit/8e4251712d721a17b9caa4f1ad04e9c2c06822a0))
+* **client:** support proxy authentication ([60effd3](https://github.com/imagekit-developer/imagekit-java/commit/60effd33a60b70e3f44e9180927e3a63a93ee00d))
+* support setting headers via env ([c31a472](https://github.com/imagekit-developer/imagekit-java/commit/c31a472fd2674c2e339d16024cb47bf246994a38))
+
+
+### Performance Improvements
+
+* **client:** create one json mapper ([92128db](https://github.com/imagekit-developer/imagekit-java/commit/92128db5fbd82870290b9c1b5003115dd7c04469))
+
+
+### Chores
+
+* remove duplicated dokka setup ([a1a0ece](https://github.com/imagekit-developer/imagekit-java/commit/a1a0ece2a2e02b2dc10b6bee8d043170e3cd9681))
+
+
+### Documentation
+
+* clarify forwards compat behavior ([d5ec8cf](https://github.com/imagekit-developer/imagekit-java/commit/d5ec8cffa3ebac99d70f70f7b6c4fadbe042a5be))
+
 ## 3.0.0 (2026-04-21)
 
 Full Changelog: [v0.0.1...v3.0.0](https://github.com/imagekit-developer/imagekit-java/compare/v0.0.1...v3.0.0)

README.md

@@ -2,16 +2,16 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/io.imagekit/image-kit-java)](https://central.sonatype.com/artifact/io.imagekit/image-kit-java/3.0.0)
-[![javadoc](https://javadoc.io/badge2/io.imagekit/image-kit-java/3.0.0/javadoc.svg)](https://javadoc.io/doc/io.imagekit/image-kit-java/3.0.0)
+[![Maven Central](https://img.shields.io/maven-central/v/io.imagekit/image-kit-java)](https://central.sonatype.com/artifact/io.imagekit/image-kit-java/3.1.0)
+[![javadoc](https://javadoc.io/badge2/io.imagekit/image-kit-java/3.1.0/javadoc.svg)](https://javadoc.io/doc/io.imagekit/image-kit-java/3.1.0)
 
 <!-- x-release-please-end -->
 
 The ImageKit Java SDK is a comprehensive library designed to simplify the integration of ImageKit into your server-side applications. It provides powerful tools for working with the ImageKit REST API, including building and transforming URLs, generating signed URLs for secure content delivery, verifying webhooks, and handling file uploads.
 
 <!-- x-release-please-start-version -->
 
-The REST API documentation can be found on [imagekit.io](https://imagekit.io/docs/api-reference). Javadocs are available on [javadoc.io](https://javadoc.io/doc/io.imagekit/image-kit-java/3.0.0).
+The REST API documentation can be found on [imagekit.io](https://imagekit.io/docs/api-reference). Javadocs are available on [javadoc.io](https://javadoc.io/doc/io.imagekit/image-kit-java/3.1.0).
 
 <!-- x-release-please-end -->
 
@@ -46,7 +46,7 @@ The REST API documentation can be found on [imagekit.io](https://imagekit.io/doc
 ### Gradle
 
 ```kotlin
-implementation("io.imagekit:image-kit-java:3.0.0")
+implementation("io.imagekit:image-kit-java:3.1.0")
 ```
 
 ### Maven
@@ -55,7 +55,7 @@ implementation("io.imagekit:image-kit-java:3.0.0")
 <dependency>
   <groupId>io.imagekit</groupId>
   <artifactId>image-kit-java</artifactId>
-  <version>3.0.0</version>
+  <version>3.1.0</version>
 </dependency>
 ```
 
@@ -615,8 +615,6 @@ The SDK throws custom unchecked exception types:
 
 ## Logging
 
-The SDK uses the standard [OkHttp logging interceptor](https://github.com/square/okhttp/tree/master/okhttp-logging-interceptor).
-
 Enable logging by setting the `IMAGE_KIT_LOG` environment variable to `info`:
 
 ```sh
@@ -629,6 +627,19 @@ Or to `debug` for more verbose logging:
 export IMAGE_KIT_LOG=debug
 ```
 
+Or configure the client manually using the `logLevel` method:
+
+```java
+import io.imagekit.client.ImageKitClient;
+import io.imagekit.client.okhttp.ImageKitOkHttpClient;
+import io.imagekit.core.LogLevel;
+
+ImageKitClient client = ImageKitOkHttpClient.builder()
+    .fromEnv()
+    .logLevel(LogLevel.INFO)
+    .build();
+```
+
 ## ProGuard and R8
 
 Although the SDK uses reflection, it is still usable with [ProGuard](https://github.com/Guardsquare/proguard) and [R8](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization) because `image-kit-java-core` is published with a [configuration file](image-kit-java-core/src/main/resources/META-INF/proguard/image-kit-java-core.pro) containing [keep rules](https://www.guardsquare.com/manual/configuration/usage).
@@ -723,6 +734,21 @@ ImageKitClient client = ImageKitOkHttpClient.builder()
     .build();
 ```
 
+If the proxy responds with `407 Proxy Authentication Required`, supply credentials by also configuring `proxyAuthenticator`:
+
+```java
+import io.imagekit.client.ImageKitClient;
+import io.imagekit.client.okhttp.ImageKitOkHttpClient;
+import io.imagekit.core.http.ProxyAuthenticator;
+
+ImageKitClient client = ImageKitOkHttpClient.builder()
+    .fromEnv()
+    .proxy(...)
+    // Or a custom implementation of `ProxyAuthenticator`.
+    .proxyAuthenticator(ProxyAuthenticator.basic("username", "password"))
+    .build();
+```
+
 ### Connection pooling
 
 To customize the underlying OkHttp connection pool, configure the client using the `maxIdleConnections` and `keepAliveDuration` methods:
@@ -961,7 +987,9 @@ In rare cases, the API may return a response that doesn't match the expected typ
 
 By default, the SDK will not throw an exception in this case. It will throw [`ImageKitInvalidDataException`](image-kit-java-core/src/main/kotlin/io/imagekit/errors/ImageKitInvalidDataException.kt) only if you directly access the property.
 
-If you would prefer to check that the response is completely well-typed upfront, then either call `validate()`:
+Validating the response is _not_ forwards compatible with new types from the API for existing fields.
+
+If you would still prefer to check that the response is completely well-typed upfront, then either call `validate()`:
 
 ```java
 import io.imagekit.models.files.FileUploadResponse;

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "io.imagekit"
-    version = "3.0.0" // x-release-please-version
+    version = "3.1.0" // x-release-please-version
 }
 
 subprojects {
@@ -21,7 +21,6 @@ subprojects {
         group = "Verification"
         description = "Verifies all source files are formatted."
     }
-    apply(plugin = "org.jetbrains.dokka")
 }
 
 subprojects {

image-kit-java-client-okhttp/build.gradle.kts

@@ -7,7 +7,6 @@ dependencies {
     api(project(":image-kit-java-core"))
 
     implementation("com.squareup.okhttp3:okhttp:4.12.0")
-    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")
 
     testImplementation(kotlin("test"))
     testImplementation("org.assertj:assertj-core:3.27.7")

image-kit-java-client-okhttp/src/main/kotlin/io/imagekit/client/okhttp/ImageKitOkHttpClient.kt

@@ -6,10 +6,12 @@ import com.fasterxml.jackson.databind.json.JsonMapper
 import io.imagekit.client.ImageKitClient
 import io.imagekit.client.ImageKitClientImpl
 import io.imagekit.core.ClientOptions
+import io.imagekit.core.LogLevel
 import io.imagekit.core.Sleeper
 import io.imagekit.core.Timeout
 import io.imagekit.core.http.Headers
 import io.imagekit.core.http.HttpClient
+import io.imagekit.core.http.ProxyAuthenticator
 import io.imagekit.core.http.QueryParams
 import io.imagekit.core.jsonMapper
 import java.net.Proxy
@@ -47,6 +49,7 @@ class ImageKitOkHttpClient private constructor() {
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var dispatcherExecutorService: ExecutorService? = null
         private var proxy: Proxy? = null
+        private var proxyAuthenticator: ProxyAuthenticator? = null
         private var maxIdleConnections: Int? = null
         private var keepAliveDuration: Duration? = null
         private var sslSocketFactory: SSLSocketFactory? = null
@@ -77,6 +80,20 @@ class ImageKitOkHttpClient private constructor() {
         /** Alias for calling [Builder.proxy] with `proxy.orElse(null)`. */
         fun proxy(proxy: Optional<Proxy>) = proxy(proxy.getOrNull())
 
+        /**
+         * Provides credentials when an HTTP proxy responds with `407 Proxy Authentication
+         * Required`.
+         */
+        fun proxyAuthenticator(proxyAuthenticator: ProxyAuthenticator?) = apply {
+            this.proxyAuthenticator = proxyAuthenticator
+        }
+
+        /**
+         * Alias for calling [Builder.proxyAuthenticator] with `proxyAuthenticator.orElse(null)`.
+         */
+        fun proxyAuthenticator(proxyAuthenticator: Optional<ProxyAuthenticator>) =
+            proxyAuthenticator(proxyAuthenticator.getOrNull())
+
         /**
          * The maximum number of idle connections kept by the underlying OkHttp connection pool.
          *
@@ -217,6 +234,9 @@ class ImageKitOkHttpClient private constructor() {
         /**
          * Whether to call `validate` on every response before returning it.
          *
+         * Setting this to `true` is _not_ forwards compatible with new types from the API for
+         * existing fields.
+         *
          * Defaults to false, which means the shape of the response will not be validated upfront.
          * Instead, validation will only occur for the parts of the response that are accessed.
          */
@@ -258,6 +278,15 @@ class ImageKitOkHttpClient private constructor() {
          */
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 
+        /**
+         * The level at which to log request and response information.
+         *
+         * [fromEnv] will set the level from environment variables. See [LogLevel.fromEnv].
+         *
+         * Defaults to [LogLevel.fromEnv].
+         */
+        fun logLevel(logLevel: LogLevel) = apply { clientOptions.logLevel(logLevel) }
+
         /**
          * Your ImageKit private API key (starts with `private_`). You can find this in the
          * [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys).
@@ -388,6 +417,7 @@ class ImageKitOkHttpClient private constructor() {
                         OkHttpClient.builder()
                             .timeout(clientOptions.timeout())
                             .proxy(proxy)
+                            .proxyAuthenticator(proxyAuthenticator)
                             .maxIdleConnections(maxIdleConnections)
                             .keepAliveDuration(keepAliveDuration)
                             .dispatcherExecutorService(dispatcherExecutorService)

image-kit-java-client-okhttp/src/main/kotlin/io/imagekit/client/okhttp/ImageKitOkHttpClientAsync.kt

@@ -6,10 +6,12 @@ import com.fasterxml.jackson.databind.json.JsonMapper
 import io.imagekit.client.ImageKitClientAsync
 import io.imagekit.client.ImageKitClientAsyncImpl
 import io.imagekit.core.ClientOptions
+import io.imagekit.core.LogLevel
 import io.imagekit.core.Sleeper
 import io.imagekit.core.Timeout
 import io.imagekit.core.http.Headers
 import io.imagekit.core.http.HttpClient
+import io.imagekit.core.http.ProxyAuthenticator
 import io.imagekit.core.http.QueryParams
 import io.imagekit.core.jsonMapper
 import java.net.Proxy
@@ -47,6 +49,7 @@ class ImageKitOkHttpClientAsync private constructor() {
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var dispatcherExecutorService: ExecutorService? = null
         private var proxy: Proxy? = null
+        private var proxyAuthenticator: ProxyAuthenticator? = null
         private var maxIdleConnections: Int? = null
         private var keepAliveDuration: Duration? = null
         private var sslSocketFactory: SSLSocketFactory? = null
@@ -77,6 +80,20 @@ class ImageKitOkHttpClientAsync private constructor() {
         /** Alias for calling [Builder.proxy] with `proxy.orElse(null)`. */
         fun proxy(proxy: Optional<Proxy>) = proxy(proxy.getOrNull())
 
+        /**
+         * Provides credentials when an HTTP proxy responds with `407 Proxy Authentication
+         * Required`.
+         */
+        fun proxyAuthenticator(proxyAuthenticator: ProxyAuthenticator?) = apply {
+            this.proxyAuthenticator = proxyAuthenticator
+        }
+
+        /**
+         * Alias for calling [Builder.proxyAuthenticator] with `proxyAuthenticator.orElse(null)`.
+         */
+        fun proxyAuthenticator(proxyAuthenticator: Optional<ProxyAuthenticator>) =
+            proxyAuthenticator(proxyAuthenticator.getOrNull())
+
         /**
          * The maximum number of idle connections kept by the underlying OkHttp connection pool.
          *
@@ -217,6 +234,9 @@ class ImageKitOkHttpClientAsync private constructor() {
         /**
          * Whether to call `validate` on every response before returning it.
          *
+         * Setting this to `true` is _not_ forwards compatible with new types from the API for
+         * existing fields.
+         *
          * Defaults to false, which means the shape of the response will not be validated upfront.
          * Instead, validation will only occur for the parts of the response that are accessed.
          */
@@ -258,6 +278,15 @@ class ImageKitOkHttpClientAsync private constructor() {
          */
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 
+        /**
+         * The level at which to log request and response information.
+         *
+         * [fromEnv] will set the level from environment variables. See [LogLevel.fromEnv].
+         *
+         * Defaults to [LogLevel.fromEnv].
+         */
+        fun logLevel(logLevel: LogLevel) = apply { clientOptions.logLevel(logLevel) }
+
         /**
          * Your ImageKit private API key (starts with `private_`). You can find this in the
          * [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys).
@@ -388,6 +417,7 @@ class ImageKitOkHttpClientAsync private constructor() {
                         OkHttpClient.builder()
                             .timeout(clientOptions.timeout())
                             .proxy(proxy)
+                            .proxyAuthenticator(proxyAuthenticator)
                             .maxIdleConnections(maxIdleConnections)
                             .keepAliveDuration(keepAliveDuration)
                             .dispatcherExecutorService(dispatcherExecutorService)