imagekitio 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dceef4a09889f51f86bee19828978c7abed42adbd5e8c538b0d12127c47b8537
-  data.tar.gz: cefed9c3863102011bb13414b9484f7aff33fde88c663f24d59e6c04a591b5b2
+  metadata.gz: 6717d24cd84488c01c7393c38be3ac3c51ef9f217b4d9492f32c68eb6d3df003
+  data.tar.gz: 919ade7e57e4398449e88960776149fba5330d6372bcdda23c565d0611cbd575
 SHA512:
-  metadata.gz: 537fc82f6b32dfc0c143e2e534e08e631892ade9382cb6142a9575d8a4da5c4a5c04df5429fc9e724f8bdd12457c3b14a705b5910f2859bf1b68543804bf8dbe
-  data.tar.gz: 8d70ce2f62eb84f4b95303421706f573f5b146aba67e819c458fb592a9458ae6da58993386f54cc7f107acdefa17b343ae9c7d4a927e5c08ada7e0652d2ef2ab
+  metadata.gz: 1253e7406eab7e10d9433e87a5b09bc5bcd6949650cfd9c8780a8ebf0e21972fb31817825dec837e86dc43acfb14af3a2cd53fb04f3f35d9e3643e2510f992fd
+  data.tar.gz: 30dd22521808a03e97eb958ffdde26953606a3203af915dbfab69f7413c7f9ee5dd9aca905ffed50f7c9d4d06c777d893a2ce81b0af95e0374c8333d996f4d27

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 4.1.0 (2026-01-16)
+
+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))
+* remove redundant base64 require statement ([4c73b42](https://github.com/imagekit-developer/imagekit-ruby/commit/4c73b425564e980b21dfd1f3554f8a2e45aaeecf))
+
+
+### 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)

data/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 -->

data/lib/imagekitio/client.rb

@@ -31,6 +31,9 @@ module Imagekitio
     # @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 @@ module Imagekitio
 
       @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)

data/lib/imagekitio/helpers/helper.rb

@@ -626,6 +626,10 @@ module Imagekitio
 
     # 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

data/lib/imagekitio/helpers/transformation_utils.rb

@@ -82,6 +82,9 @@ module Imagekitio
       "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 Imagekitio
       "line_height" => "lh",
       "lineHeight" => "lh",
 
+      # Overlay transformations
+      "layer_mode" => "lm",
+      "layerMode" => "lm",
+
       # Subtitles transformations
       "font_outline" => "fol",
       "fontOutline" => "fol",

data/lib/imagekitio/internal/transport/base_client.rb

@@ -201,7 +201,8 @@ module Imagekitio
             self.class::PLATFORM_HEADERS,
             {
               "accept" => "application/json",
-              "content-type" => "application/json"
+              "content-type" => "application/json",
+              "user-agent" => user_agent
             },
             headers
           )
@@ -219,6 +220,11 @@ module Imagekitio
         # @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]

data/lib/imagekitio/internal/transport/pooled_net_requester.rb

@@ -16,10 +16,11 @@ module Imagekitio
         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 @@ module Imagekitio
               _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 @@ module Imagekitio
           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 @@ module Imagekitio
                   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 @@ module Imagekitio
         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
 

data/lib/imagekitio/internal/type/base_model.rb

@@ -440,6 +440,7 @@ module Imagekitio
         # @example
         #   # `base_overlay` is a `Imagekitio::BaseOverlay`
         #   base_overlay => {
+        #     layer_mode: layer_mode,
         #     position: position,
         #     timing: timing
         #   }

data/lib/imagekitio/internal/type/union.rb

@@ -6,16 +6,28 @@ module Imagekitio
       # @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

data/lib/imagekitio/internal/util.rb

@@ -657,7 +657,8 @@ module Imagekitio
         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 @@ module Imagekitio
           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)

data/lib/imagekitio/models/base_overlay.rb

@@ -3,19 +3,89 @@
 module Imagekitio
   module Models
     class BaseOverlay < Imagekitio::Internal::Type::BaseModel
+      # @!attribute layer_mode
+      #   Controls how the layer blends with the base image or underlying content. Maps to
+      #   `lm` in the URL. By default, layers completely cover the base image beneath
+      #   them. Layer modes change this behavior:
+      #
+      #   - `multiply`: Multiplies the pixel values of the layer with the base image. The
+      #     result is always darker than the original images. This is ideal for applying
+      #     shadows or color tints.
+      #   - `displace`: Uses the layer as a displacement map to distort pixels in the base
+      #     image. The red channel controls horizontal displacement, and the green channel
+      #     controls vertical displacement. Requires `x` or `y` parameter to control
+      #     displacement magnitude.
+      #   - `cutout`: Acts as an inverse mask where opaque areas of the layer turn the
+      #     base image transparent, while transparent areas leave the base image
+      #     unchanged. This mode functions like a hole-punch, effectively cutting the
+      #     shape of the layer out of the underlying image.
+      #   - `cutter`: Acts as a shape mask where only the parts of the base image that
+      #     fall inside the opaque area of the layer are preserved. This mode functions
+      #     like a cookie-cutter, trimming the base image to match the specific dimensions
+      #     and shape of the layer. See
+      #     [Layer modes](https://imagekit.io/docs/add-overlays-on-images#layer-modes).
+      #
+      #   @return [Symbol, Imagekitio::Models::BaseOverlay::LayerMode, nil]
+      optional :layer_mode, enum: -> { Imagekitio::BaseOverlay::LayerMode }, api_name: :layerMode
+
       # @!attribute position
+      #   Specifies the overlay's position relative to the parent asset. See
+      #   [Position of Layer](https://imagekit.io/docs/transformations#position-of-layer).
       #
       #   @return [Imagekitio::Models::OverlayPosition, nil]
       optional :position, -> { Imagekitio::OverlayPosition }
 
       # @!attribute timing
+      #   Specifies timing information for the overlay (only applicable if the base asset
+      #   is a video). See
+      #   [Position of Layer](https://imagekit.io/docs/transformations#position-of-layer).
       #
       #   @return [Imagekitio::Models::OverlayTiming, nil]
       optional :timing, -> { Imagekitio::OverlayTiming }
 
-      # @!method initialize(position: nil, timing: nil)
-      #   @param position [Imagekitio::Models::OverlayPosition]
-      #   @param timing [Imagekitio::Models::OverlayTiming]
+      # @!method initialize(layer_mode: nil, position: nil, timing: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Imagekitio::Models::BaseOverlay} for more details.
+      #
+      #   @param layer_mode [Symbol, Imagekitio::Models::BaseOverlay::LayerMode] Controls how the layer blends with the base image or underlying content. Maps to
+      #
+      #   @param position [Imagekitio::Models::OverlayPosition] Specifies the overlay's position relative to the parent asset.
+      #
+      #   @param timing [Imagekitio::Models::OverlayTiming] Specifies timing information for the overlay (only applicable if the base asset
+
+      # Controls how the layer blends with the base image or underlying content. Maps to
+      # `lm` in the URL. By default, layers completely cover the base image beneath
+      # them. Layer modes change this behavior:
+      #
+      # - `multiply`: Multiplies the pixel values of the layer with the base image. The
+      #   result is always darker than the original images. This is ideal for applying
+      #   shadows or color tints.
+      # - `displace`: Uses the layer as a displacement map to distort pixels in the base
+      #   image. The red channel controls horizontal displacement, and the green channel
+      #   controls vertical displacement. Requires `x` or `y` parameter to control
+      #   displacement magnitude.
+      # - `cutout`: Acts as an inverse mask where opaque areas of the layer turn the
+      #   base image transparent, while transparent areas leave the base image
+      #   unchanged. This mode functions like a hole-punch, effectively cutting the
+      #   shape of the layer out of the underlying image.
+      # - `cutter`: Acts as a shape mask where only the parts of the base image that
+      #   fall inside the opaque area of the layer are preserved. This mode functions
+      #   like a cookie-cutter, trimming the base image to match the specific dimensions
+      #   and shape of the layer. See
+      #   [Layer modes](https://imagekit.io/docs/add-overlays-on-images#layer-modes).
+      #
+      # @see Imagekitio::Models::BaseOverlay#layer_mode
+      module LayerMode
+        extend Imagekitio::Internal::Type::Enum
+
+        MULTIPLY = :multiply
+        CUTTER = :cutter
+        CUTOUT = :cutout
+        DISPLACE = :displace
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
     end
   end
 end

data/lib/imagekitio/models/beta/v2/file_upload_params.rb

@@ -149,7 +149,7 @@ module Imagekitio
           #   Array of extensions to be applied to the asset. Each extension can be configured
           #   with specific parameters based on the extension type.
           #
-          #   @return [Array<Imagekitio::Models::ExtensionItem::RemoveBg, Imagekitio::Models::ExtensionItem::AIAutoDescription, Imagekitio::Models::ExtensionItem::AutoTaggingExtension>, nil]
+          #   @return [Array<Imagekitio::Models::ExtensionItem::RemoveBg, Imagekitio::Models::ExtensionItem::AIAutoDescription, Imagekitio::Models::ExtensionItem::AITasks, Imagekitio::Models::ExtensionItem::SavedExtension, Imagekitio::Models::ExtensionItem::AutoTaggingExtension>, nil]
           optional :extensions, -> { Imagekitio::Internal::Type::ArrayOf[union: Imagekitio::ExtensionItem] }
 
           # @!attribute folder
@@ -286,7 +286,7 @@ module Imagekitio
           #
           #   @param description [String] Optional text to describe the contents of the file.
           #
-          #   @param extensions [Array<Imagekitio::Models::ExtensionItem::RemoveBg, Imagekitio::Models::ExtensionItem::AIAutoDescription, Imagekitio::Models::ExtensionItem::AutoTaggingExtension>] Array of extensions to be applied to the asset. Each extension can be configured
+          #   @param extensions [Array<Imagekitio::Models::ExtensionItem::RemoveBg, Imagekitio::Models::ExtensionItem::AIAutoDescription, Imagekitio::Models::ExtensionItem::AITasks, Imagekitio::Models::ExtensionItem::SavedExtension, Imagekitio::Models::ExtensionItem::AutoTaggingExtension>] Array of extensions to be applied to the asset. Each extension can be configured
           #
           #   @param folder [String] The folder path in which the image has to be uploaded. If the folder(s) didn't e
           #

data/lib/imagekitio/models/beta/v2/file_upload_response.rb

@@ -299,6 +299,13 @@ module Imagekitio
                      enum: -> { Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus::AIAutoDescription },
                      api_name: :"ai-auto-description"
 
+            # @!attribute ai_tasks
+            #
+            #   @return [Symbol, Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus::AITasks, nil]
+            optional :ai_tasks,
+                     enum: -> { Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus::AITasks },
+                     api_name: :"ai-tasks"
+
             # @!attribute aws_auto_tagging
             #
             #   @return [Symbol, Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus::AwsAutoTagging, nil]
@@ -320,7 +327,7 @@ module Imagekitio
                      enum: -> { Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus::RemoveBg },
                      api_name: :"remove-bg"
 
-            # @!method initialize(ai_auto_description: nil, aws_auto_tagging: nil, google_auto_tagging: nil, remove_bg: nil)
+            # @!method initialize(ai_auto_description: nil, ai_tasks: nil, aws_auto_tagging: nil, google_auto_tagging: nil, remove_bg: nil)
             #   Extension names with their processing status at the time of completion of the
             #   request. It could have one of the following status values:
             #
@@ -332,6 +339,7 @@ module Imagekitio
             #   If no extension was requested, then this parameter is not returned.
             #
             #   @param ai_auto_description [Symbol, Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus::AIAutoDescription]
+            #   @param ai_tasks [Symbol, Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus::AITasks]
             #   @param aws_auto_tagging [Symbol, Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus::AwsAutoTagging]
             #   @param google_auto_tagging [Symbol, Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus::GoogleAutoTagging]
             #   @param remove_bg [Symbol, Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus::RemoveBg]
@@ -348,6 +356,18 @@ module Imagekitio
               #   @return [Array<Symbol>]
             end
 
+            # @see Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus#ai_tasks
+            module AITasks
+              extend Imagekitio::Internal::Type::Enum
+
+              SUCCESS = :success
+              PENDING = :pending
+              FAILED = :failed
+
+              # @!method self.values
+              #   @return [Array<Symbol>]
+            end
+
             # @see Imagekitio::Models::Beta::V2::FileUploadResponse::ExtensionStatus#aws_auto_tagging
             module AwsAutoTagging
               extend Imagekitio::Internal::Type::Enum