release: 4.1.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.0.0"
+  ".": "4.1.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 42
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-9d184cb502ab32a85db2889c796cdfebe812f2a55a604df79c85dd4b5e7e2add.yml
-openapi_spec_hash: a9aa620376fce66532c84f9364209b0b
-config_hash: eb4cf65a4c6b26a2901076eff5810d5d
+configured_endpoints: 47
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-c028a7584d3508f268ce5c5b824b50af88eaa140620dd03a1b35f409f510603c.yml
+openapi_spec_hash: f9b780b2398a87678a13355e48cd515f
+config_hash: aeb6eb949d73382270bbd8bbf2e4cf2a

CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 4.1.0 (2026-01-15)
+
+Full Changelog: [v4.0.0...v4.1.0](https://github.com/imagekit-developer/imagekit-ruby/compare/v4.0.0...v4.1.0)
+
+### Features
+
+* add layer_mode property to overlays and new transformation options ([97042ce](https://github.com/imagekit-developer/imagekit-ruby/commit/97042ce9bffaf101ab98dd7394caaf4df9a873ea))
+* **api:** Add saved extensions API and enhance transformation options ([f1dc75e](https://github.com/imagekit-developer/imagekit-ruby/commit/f1dc75ecbe0a4a39472fdc10e9dc8f02e75ddc07))
+
+
+### Bug Fixes
+
+* add ai-tasks property to response schemas with enum values ([aad5e54](https://github.com/imagekit-developer/imagekit-ruby/commit/aad5e5413676af916e8149f07ae78aaff7c5c313))
+* better thread safety via early initializing SSL store during HTTP client creation ([2bc0835](https://github.com/imagekit-developer/imagekit-ruby/commit/2bc0835981c29b717f0ad3a7d78c3c78027874e0))
+* calling `break` out of streams should be instantaneous ([55bf4a9](https://github.com/imagekit-developer/imagekit-ruby/commit/55bf4a9b768f18f4adad903b2c9d93178a670151))
+* issue where json.parse errors when receiving HTTP 204 with nobody ([dd32cb1](https://github.com/imagekit-developer/imagekit-ruby/commit/dd32cb1572bc155db85ed898011374889996b3fd))
+
+
+### Chores
+
+* bump dependency version and update sorbet types ([8d89fb2](https://github.com/imagekit-developer/imagekit-ruby/commit/8d89fb2c1654420f83bb7efedcc9056c5a7e3c79))
+* **client:** send user-agent header ([796027d](https://github.com/imagekit-developer/imagekit-ruby/commit/796027d185c93067c32bac98323d8a82aeaf9bfe))
+* explicitly require "base64" gem ([1b4181d](https://github.com/imagekit-developer/imagekit-ruby/commit/1b4181d4e57d2c12306f6d3f43b832f63ab68053))
+* **internal:** codegen related update ([3a93def](https://github.com/imagekit-developer/imagekit-ruby/commit/3a93def2d09609b359824a627183833ae59d74e1))
+* **internal:** codegen related update ([4c161f0](https://github.com/imagekit-developer/imagekit-ruby/commit/4c161f048927df137a12d33a5a1b79af1c561b8b))
+* move `cgi` into dependencies for ruby 4 ([54261ef](https://github.com/imagekit-developer/imagekit-ruby/commit/54261ef9f24e206d2180dc0a205464154af4c3ed))
+
+
+### Documentation
+
+* prominently feature MCP server setup in root SDK readmes ([777f8cf](https://github.com/imagekit-developer/imagekit-ruby/commit/777f8cf5cc692eed3e8f6217caf25a85d17201f7))
+* remove MCP Server section from README ([db0f71c](https://github.com/imagekit-developer/imagekit-ruby/commit/db0f71cce159f4c395fe8c7c0526d4108934fc6b))
+
 ## 4.0.0 (2025-11-03)
 
 Full Changelog: [v0.0.1...v4.0.0](https://github.com/imagekit-developer/imagekit-ruby/compare/v0.0.1...v4.0.0)

Gemfile

@@ -11,8 +11,7 @@ group :development do
   gem "sorbet"
   gem "steep"
   gem "syntax_tree"
-  # TODO: using a fork for now, the prettier below has a bug
-  gem "syntax_tree-rbs", github: "stainless-api/syntax_tree-rbs", branch: "main"
+  gem "syntax_tree-rbs", github: "ruby-syntax-tree/syntax_tree-rbs", branch: "main"
   gem "tapioca"
 end
 

Gemfile.lock

@@ -1,6 +1,6 @@
 GIT
-  remote: https://github.com/stainless-api/syntax_tree-rbs.git
-  revision: c30b50219918be7cfe3ef803a00b59d1e77fcada
+  remote: https://github.com/ruby-syntax-tree/syntax_tree-rbs.git
+  revision: f94bc3060682ffbd126e4d5086ffedc89073d626
   branch: main
   specs:
     syntax_tree-rbs (1.0.0)
@@ -11,7 +11,8 @@ GIT
 PATH
   remote: .
   specs:
-    imagekitio (4.0.0)
+    imagekitio (4.1.0)
+      cgi
       connection_pool
 
 GEM
@@ -42,6 +43,7 @@ GEM
     base64 (0.3.0)
     benchmark (0.5.0)
     bigdecimal (3.3.1)
+    cgi (0.5.1)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.4)
     console (1.34.2)

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 ImageKit
+   Copyright 2026 Image Kit
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -45,7 +45,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "imagekitio", "~> 4.0.0"
+gem "imagekitio", "~> 4.1.0"
 ```
 
 <!-- x-release-please-end -->

imagekitio.gemspec

@@ -24,5 +24,6 @@ Gem::Specification.new do |s|
     ".ignore"
   ]
   s.extra_rdoc_files = ["README.md"]
+  s.add_dependency "cgi"
   s.add_dependency "connection_pool"
 end

lib/imagekitio.rb

@@ -3,12 +3,14 @@
 # Standard libraries.
 # rubocop:disable Lint/RedundantRequireStatement
 require "English"
+require "base64"
 require "cgi"
 require "date"
 require "erb"
 require "etc"
 require "json"
 require "net/http"
+require "openssl"
 require "pathname"
 require "rbconfig"
 require "securerandom"
@@ -16,7 +18,7 @@
 require "stringio"
 require "time"
 require "uri"
 require "base64"
 # rubocop:enable Lint/RedundantRequireStatement
 
 # We already ship the preferred sorbet manifests in the package itself.
@@ -89,6 +91,7 @@
 require_relative "imagekitio/models/custom_metadata_field_list_params"
 require_relative "imagekitio/models/custom_metadata_field_list_response"
 require_relative "imagekitio/models/custom_metadata_field_update_params"
+require_relative "imagekitio/models/extension_config"
 require_relative "imagekitio/models/extensions"
 require_relative "imagekitio/models/file_copy_params"
 require_relative "imagekitio/models/file_copy_response"
@@ -138,6 +141,13 @@
 require_relative "imagekitio/models/overlay_position"
 require_relative "imagekitio/models/overlay_timing"
 require_relative "imagekitio/models/responsive_image_attributes"
+require_relative "imagekitio/models/saved_extension"
+require_relative "imagekitio/models/saved_extension_create_params"
+require_relative "imagekitio/models/saved_extension_delete_params"
+require_relative "imagekitio/models/saved_extension_get_params"
+require_relative "imagekitio/models/saved_extension_list_params"
+require_relative "imagekitio/models/saved_extension_list_response"
+require_relative "imagekitio/models/saved_extension_update_params"
 require_relative "imagekitio/models/solid_color_overlay"
 require_relative "imagekitio/models/solid_color_overlay_transformation"
 require_relative "imagekitio/models/streaming_resolution"
@@ -177,5 +187,6 @@
 require_relative "imagekitio/resources/files/versions"
 require_relative "imagekitio/resources/folders"
 require_relative "imagekitio/resources/folders/job"
+require_relative "imagekitio/resources/saved_extensions"
 require_relative "imagekitio/resources/webhooks"
 require_relative "imagekitio/helpers/helper"

lib/imagekitio/client.rb

@@ -31,6 +31,9 @@ class Client < Imagekitio::Internal::Transport::BaseClient
     # @return [Imagekitio::Resources::Files]
     attr_reader :files
 
+    # @return [Imagekitio::Resources::SavedExtensions]
+    attr_reader :saved_extensions
+
     # @return [Imagekitio::Resources::Assets]
     attr_reader :assets
 
@@ -117,6 +120,7 @@ def initialize(
 
       @custom_metadata_fields = Imagekitio::Resources::CustomMetadataFields.new(client: self)
       @files = Imagekitio::Resources::Files.new(client: self)
+      @saved_extensions = Imagekitio::Resources::SavedExtensions.new(client: self)
       @assets = Imagekitio::Resources::Assets.new(client: self)
       @cache = Imagekitio::Resources::Cache.new(client: self)
       @folders = Imagekitio::Resources::Folders.new(client: self)

lib/imagekitio/helpers/helper.rb

@@ -626,6 +626,10 @@ def safe_get(obj, key)
 
     # Add overlay properties like position, timing, transformations (matching Node.js)
     def add_overlay_properties(parts, overlay)
+      # Add layer_mode property
+      layer_mode = safe_get(overlay, :layer_mode)
+      parts << "lm-#{layer_mode}" if layer_mode
+
       # Add position properties
       position = safe_get(overlay, :position)
       if position

lib/imagekitio/helpers/transformation_utils.rb

@@ -82,6 +82,9 @@ module TransformationUtils
       "unsharp_mask" => "e-usm",
       "unsharpMask" => "e-usm",
       "gradient" => "e-gradient",
+      "color_replace" => "cr",
+      "colorReplace" => "cr",
+      "distort" => "e-distort",
 
       # Other flags & finishing
       "progressive" => "pr",
@@ -109,6 +112,10 @@ module TransformationUtils
       "line_height" => "lh",
       "lineHeight" => "lh",
 
+      # Overlay transformations
+      "layer_mode" => "lm",
+      "layerMode" => "lm",
+
       # Subtitles transformations
       "font_outline" => "fol",
       "fontOutline" => "fol",

lib/imagekitio/internal/transport/base_client.rb

@@ -201,7 +201,8 @@ def initialize(
             self.class::PLATFORM_HEADERS,
             {
               "accept" => "application/json",
-              "content-type" => "application/json"
+              "content-type" => "application/json",
+              "user-agent" => user_agent
             },
             headers
           )
@@ -219,6 +220,11 @@ def initialize(
         # @return [Hash{String=>String}]
         private def auth_headers = {}
 
+        # @api private
+        #
+        # @return [String]
+        private def user_agent = "#{self.class.name}/Ruby #{Imagekitio::VERSION}"
+
         # @api private
         #
         # @return [String]

lib/imagekitio/internal/transport/pooled_net_requester.rb

@@ -16,10 +16,11 @@ class PooledNetRequester
         class << self
           # @api private
           #
+          # @param cert_store [OpenSSL::X509::Store]
           # @param url [URI::Generic]
           #
           # @return [Net::HTTP]
-          def connect(url)
+          def connect(cert_store:, url:)
             port =
               case [url.port, url.scheme]
               in [Integer, _]
@@ -34,18 +35,7 @@ def connect(url)
               _1.use_ssl = %w[https wss].include?(url.scheme)
               _1.max_retries = 0
 
-              # Temporary workaround for SSL verification issue on some
-              # platforms. Similar to: https://github.com/stripe/stripe-ruby/pull/397
-              # Without this fix you may see errors like:
-              # .rbenv/versions/3.2.0/lib/ruby/3.2.0/net/protocol.rb:46:in `connect_nonblock':
-              # SSL_connect returned=1 errno=0 peeraddr=52.23.130.57:443 state=error:
-              # certificate verify failed (unable to get certificate CRL) (OpenSSL::SSL::SSLError)
-              if _1.use_ssl?
-                cert_store = OpenSSL::X509::Store.new
-                cert_store.set_default_paths
-                _1.cert_store = cert_store
-                _1.verify_mode = OpenSSL::SSL::VERIFY_PEER
-              end
+              (_1.cert_store = cert_store) if _1.use_ssl?
             end
           end
 
@@ -115,7 +105,7 @@ def build_request(request, &blk)
           pool =
             @mutex.synchronize do
               @pools[origin] ||= ConnectionPool.new(size: @size) do
-                self.class.connect(url)
+                self.class.connect(cert_store: @cert_store, url: url)
               end
             end
 
@@ -163,17 +153,19 @@ def execute(request)
                   end
 
                   self.class.calibrate_socket_timeout(conn, deadline)
-                  conn.request(req) do |rsp|
-                    y << [req, rsp]
-                    break if finished
-
-                    rsp.read_body do |bytes|
-                      y << bytes.force_encoding(Encoding::BINARY)
-                      break if finished
-
-                      self.class.calibrate_socket_timeout(conn, deadline)
+                  ::Kernel.catch(:jump) do
+                    conn.request(req) do |rsp|
+                      y << [req, rsp]
+                      ::Kernel.throw(:jump) if finished
+
+                      rsp.read_body do |bytes|
+                        y << bytes.force_encoding(Encoding::BINARY)
+                        ::Kernel.throw(:jump) if finished
+
+                        self.class.calibrate_socket_timeout(conn, deadline)
+                      end
+                      eof = true
                     end
-                    eof = true
                   end
                 end
               ensure
@@ -205,6 +197,7 @@ def execute(request)
         def initialize(size: self.class::DEFAULT_MAX_CONNECTIONS)
           @mutex = Mutex.new
           @size = size
+          @cert_store = OpenSSL::X509::Store.new.tap(&:set_default_paths)
           @pools = {}
         end
 

lib/imagekitio/internal/type/base_model.rb

@@ -440,6 +440,7 @@ def deep_to_h = self.class.recursively_to_h(@data, convert: false)
         # @example
         #   # `base_overlay` is a `Imagekitio::BaseOverlay`
         #   base_overlay => {
+        #     layer_mode: layer_mode,
         #     position: position,
         #     timing: timing
         #   }

lib/imagekitio/internal/type/union.rb

@@ -6,16 +6,28 @@ module Type
       # @api private
       #
       # @example
-      #   # `overlay` is a `Imagekitio::Overlay`
-      #   case overlay
-      #   when Imagekitio::TextOverlay
-      #     # ...
-      #   when Imagekitio::ImageOverlay
-      #     # ...
-      #   when Imagekitio::VideoOverlay
+      #   # `extension_config` is a `Imagekitio::ExtensionConfig`
+      #   case extension_config
+      #   when Imagekitio::ExtensionConfig::RemoveBg
+      #     puts(extension_config.name)
+      #   when Imagekitio::ExtensionConfig::AIAutoDescription
+      #     puts(extension_config.name)
+      #   when Imagekitio::ExtensionConfig::AITasks
+      #     puts(extension_config.tasks)
+      #   else
+      #     puts(extension_config)
+      #   end
+      #
+      # @example
+      #   case extension_config
+      #   in {name: :"remove-bg", options: options}
+      #     puts(options)
+      #   in {name: :"ai-auto-description"}
       #     # ...
+      #   in {name: :"ai-tasks", tasks: tasks}
+      #     puts(tasks)
       #   else
-      #     puts(overlay)
+      #     puts(extension_config)
       #   end
       module Union
         include Imagekitio::Internal::Type::Converter

lib/imagekitio/internal/util.rb

@@ -657,7 +657,8 @@ def force_charset!(content_type, text:)
         def decode_content(headers, stream:, suppress_error: false)
           case (content_type = headers["content-type"])
           in Imagekitio::Internal::Util::JSON_CONTENT
-            json = stream.to_a.join
+            return nil if (json = stream.to_a.join).empty?
+
             begin
               JSON.parse(json, symbolize_names: true)
             rescue JSON::ParserError => e
@@ -667,7 +668,11 @@ def decode_content(headers, stream:, suppress_error: false)
           in Imagekitio::Internal::Util::JSONL_CONTENT
             lines = decode_lines(stream)
             chain_fused(lines) do |y|
-              lines.each { y << JSON.parse(_1, symbolize_names: true) }
+              lines.each do
+                next if _1.empty?
+
+                y << JSON.parse(_1, symbolize_names: true)
+              end
             end
           in %r{^text/event-stream}
             lines = decode_lines(stream)