imgwire 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b912ed96b11a03a1ed5017b4dacb98af41a3bffebd7b34254a11fbc18d398b5
-  data.tar.gz: 57f6e83b710c3884283da8e6a772d0ad3e8e4da1cdb5696180aea496709f91ac
+  metadata.gz: df6fe59538abf5207310fee7e35a2bc69122f3e989c79bad3a674979553ddc62
+  data.tar.gz: ea52a41f725f7d9ddd339151eb1e350a815b39276caddb1db643ba8627da9a50
 SHA512:
-  metadata.gz: 97686c66dfad3d7bba07244ad8b0040bab9b29c8bb3a01a9e69e953e26eb20dc9c29401950624bb8ec61981c43169fce44dbea8eda8d87c8d7cde496a3344f9d
-  data.tar.gz: 2f268dd8db5e7479d7bde706427d533a3918f72cfe3f32d8c0f7b318c70ab6e17ab19e07a3c6dbc54cbb8d85286ee0c3df5b5ea1bea4b0f7540b925e7339824b
+  metadata.gz: fd1bfa952e82bf07d9f0c3dd517d17e6863e15a1a8107ab743c262f64a72f71a866599f2a7f79d5ff9e8c5c2ad7dcd217319732429b4e93f5c7ec0665a31d442
+  data.tar.gz: 813abc30206d27d06d109af62d0a82b6bd8068244d050a6bdfe8fbb1a4317e84012aa429c63c2d23fb8d6fecd8311469ebe2a34c92cda7229d87716fef9f3eae

data/CODEGEN_VERSION

@@ -1 +1 @@
-ff2563481f5f13c58b28b6ed0a20ff40145415791abd150cfbe89fc4b71ed7df
+b57e439d6e9c3859c7bddb889658b5ff808503ccc136ea28a56e0fd57a1678aa

data/README.md

@@ -1,6 +1,9 @@
+![imgwire.dev Logo](https://cdn.imgwire.dev/6b024480-a5ac-426d-b539-2e4fccc4c6ac/26f80c13-48bd-4bb9-866e-5e9392b11a6a/4ba5fe50-433b-40db-a847-938d2081c21a?w=280&quality=80)
+
 # `imgwire`
 
 [![RubyGems version](https://img.shields.io/gem/v/imgwire.svg)](https://rubygems.org/gems/imgwire)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/Blackhawk-Software/imgwire-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/Blackhawk-Software/imgwire-ruby/actions/workflows/ci.yml)
 [![Release](https://github.com/Blackhawk-Software/imgwire-ruby/actions/workflows/release.yml/badge.svg)](https://github.com/Blackhawk-Software/imgwire-ruby/actions/workflows/release.yml)
 
@@ -8,6 +11,9 @@
 
 Use it in Rails apps, workers, jobs, and other backend runtimes to authenticate with a Server API Key, upload files from Ruby IO objects, manage server-side resources, and generate image transformation URLs without rebuilding imgwire request plumbing yourself.
 
+> [!TIP]
+> Obtain an API key by signing up at [imgwire.dev](https://imgwire.dev). Read the full API & SDK documentation [here](https://docs.imgwire.dev/guides/backend-quickstart).
+
 ## Installation
 
 ```bash
@@ -114,6 +120,30 @@ puts image.url(
 )
 ```
 
+The helper accepts the transform names and aliases from
+`docs/imgwire-url-transformations-guide.md`. Multi-field transforms can be
+passed as their URL string syntax or as Ruby hashes:
+
+```ruby
+puts image.url(
+  gradient: {
+    colors: ["#0b1f5e", "#ff2a2a"],
+    angle: 90,
+    opacity: 0.25,
+    blend: "overlay"
+  },
+  watermark_url: "https://example.com/logo.png",
+  watermark_position: {
+    gravity: "southeast",
+    x: -24,
+    y: -24,
+    opacity: 0.85
+  }
+)
+```
+
+Out-of-range transform values are omitted from the generated URL.
+
 ## Generation
 
 From a clean checkout:

data/lib/imgwire/image.rb

@@ -1,25 +1,11 @@
 # frozen_string_literal: true
 
 require 'uri'
+require 'imgwire/url_transformations'
 
 module Imgwire
   class Image < ImgwireGenerated::ImageSchema
     PRESETS = %w[thumbnail small medium large].freeze
-    ROTATE_ANGLES = [0, 90, 180, 270, 360].freeze
-    FORMATS = %w[jpg png avif gif webp auto].freeze
-
-    RULES = {
-      'background' => %w[background bg],
-      'crop' => %w[crop],
-      'enlarge' => %w[enlarge],
-      'format' => %w[format fm],
-      'gravity' => %w[gravity],
-      'height' => %w[height h],
-      'quality' => %w[quality q],
-      'rotate' => %w[rotate rot],
-      'strip_metadata' => %w[strip_metadata strip],
-      'width' => %w[width w]
-    }.freeze
 
     def self.wrap(value)
       return value if value.is_a?(self)
@@ -38,7 +24,7 @@ module Imgwire
     def url(options = {})
       options = symbolize_keys(options)
       path = build_preset_path(options[:preset])
-      query = build_query(options.except(:preset))
+      query = Imgwire::URLTransformations.build_query(options.except(:preset))
 
       uri = URI.parse(cdn_url)
       uri.path = path
@@ -63,69 +49,5 @@ module Imgwire
       uri = URI.parse(cdn_url)
       "#{uri.path}@#{preset}"
     end
-
-    def build_query(options)
-      present = []
-
-      RULES.each do |canonical, aliases|
-        matches = aliases.filter_map do |name|
-          symbol = name.to_sym
-          [symbol, options[symbol]] if options.key?(symbol)
-        end
-
-        next if matches.empty?
-        raise ArgumentError, "Duplicate transformation rule: #{canonical}" if matches.length > 1
-
-        value = normalize_rule(canonical, matches.first.last)
-        present << [canonical, value] unless value.nil?
-      end
-
-      present
-    end
-
-    def normalize_rule(canonical, value)
-      case canonical
-      when 'background'
-        string = value.to_s.delete_prefix('#')
-        unless string.match?(/\A[\da-fA-F]{6}\z/)
-          raise ArgumentError,
-                "Invalid transformation rule value for #{canonical}"
-        end
-
-        string.downcase
-      when 'crop', 'gravity'
-        value.to_s
-      when 'enlarge', 'strip_metadata'
-        value ? 'true' : nil
-      when 'format'
-        string = value.to_s
-        unless FORMATS.include?(string)
-          raise ArgumentError,
-                "Invalid transformation rule value for #{canonical}"
-        end
-
-        string
-      when 'height', 'quality', 'width'
-        integer = Integer(value)
-        unless integer.positive?
-          raise ArgumentError,
-                "Invalid transformation rule value for #{canonical}"
-        end
-
-        integer.to_s
-      when 'rotate'
-        integer = Integer(value)
-        unless ROTATE_ANGLES.include?(integer)
-          raise ArgumentError,
-                "Invalid transformation rule value for #{canonical}"
-        end
-
-        integer.to_s
-      else
-        raise ArgumentError, "Unsupported transformation rule: #{canonical}"
-      end
-    rescue ArgumentError, TypeError
-      raise ArgumentError, "Invalid transformation rule value for #{canonical}"
-    end
   end
 end

data/lib/imgwire/url_transformations.rb

@@ -0,0 +1,929 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'uri'
+
+module Imgwire
+  # rubocop:disable Metrics/ModuleLength
+  module URLTransformations
+    RULES = {
+      'adjust' => %w[a adjust],
+      'background' => %w[bg background],
+      'background_alpha' => %w[bga background_alpha],
+      'blur' => %w[bl blur],
+      'brightness' => %w[br brightness],
+      'chroma_subsampling' => %w[chroma_subsampling],
+      'color_profile' => %w[cp icc color_profile],
+      'colorize' => %w[col colorize],
+      'contrast' => %w[co contrast],
+      'crop' => %w[c crop],
+      'dpi' => %w[dpi],
+      'dpr' => %w[dpr],
+      'duotone' => %w[dt duotone],
+      'enlarge' => %w[el enlarge],
+      'extend' => %w[ex extend],
+      'extend_aspect_ratio' => %w[exar extend_ar extend_aspect_ratio],
+      'flip' => %w[fl flip],
+      'format' => %w[f format ext extension fm],
+      'gradient' => %w[gr gradient],
+      'gravity' => %w[g gravity],
+      'height' => %w[h height],
+      'hue' => %w[hu hue],
+      'keep_copyright' => %w[kcr keep_copyright],
+      'lightness' => %w[l lightness],
+      'min-height' => %w[mh min_height min-height],
+      'min-width' => %w[mw min_width min-width],
+      'monochrome' => %w[mc monochrome],
+      'negate' => %w[neg negate],
+      'normalize' => %w[norm normalise normalize],
+      'padding' => %w[pd padding],
+      'pixelate' => %w[pix pixelate],
+      'progressive' => %w[progressive],
+      'quality' => %w[q quality],
+      'resizing_algorithm' => %w[ra resizing_algorithm],
+      'resizing_type' => %w[resizing_type],
+      'rotate' => %w[rot rotate],
+      'saturation' => %w[sa saturation],
+      'sharpen' => %w[sh sharpen],
+      'strip_color_profile' => %w[scp strip_color_profile],
+      'strip_metadata' => %w[sm strip_metadata strip],
+      'watermark' => %w[wm watermark],
+      'watermark_position' => %w[wmp watermark_offset watermark_position],
+      'watermark_rotate' => %w[wmr wm_rot watermark_rotate],
+      'watermark_shadow' => %w[wmsh watermark_shadow],
+      'watermark_size' => %w[wms watermark_size],
+      'watermark_text' => %w[wmt watermark_text],
+      'watermark_url' => %w[wmu watermark_url],
+      'width' => %w[w width],
+      'zoom' => %w[z zoom]
+    }.freeze
+
+    COLOR_PROFILES = %w[srgb rgb16 cmyk keep preserve].freeze
+    CHROMA_SUBSAMPLING_VALUES = %w[4:2:0 4:4:4 auto].freeze
+    FORMATS = %w[auto jpg jpeg png webp avif gif tiff].freeze
+    FLIP_VALUES = %w[vertical horizontal both].freeze
+    RESIZING_ALGORITHMS = %w[nearest cubic mitchell lanczos2 lanczos3].freeze
+    RESIZING_TYPES = %w[cover contain fill inside outside].freeze
+    RESIZING_TYPE_ALIASES = {
+      'auto' => 'inside',
+      'fill-down' => 'inside',
+      'fit' => 'inside',
+      'force' => 'fill'
+    }.freeze
+    GRAVITY_VALUES = %w[
+      ce center north south east west northeast northwest southeast southwest attention entropy
+    ].freeze
+    GRAVITY_ALIASES = {
+      'n' => 'north',
+      'no' => 'north',
+      's' => 'south',
+      'so' => 'south',
+      'e' => 'east',
+      'ea' => 'east',
+      'w' => 'west',
+      'we' => 'west',
+      'ne' => 'northeast',
+      'noea' => 'northeast',
+      'se' => 'southeast',
+      'soea' => 'southeast',
+      'nw' => 'northwest',
+      'nowe' => 'northwest',
+      'sw' => 'southwest',
+      'sowe' => 'southwest',
+      'ce:sm' => 'attention'
+    }.freeze
+
+    module_function
+
+    def build_query(options)
+      normalized_options = normalize_top_level_keys(options)
+
+      RULES.each_with_object([]) do |(canonical, aliases), present|
+        matches = aliases.filter_map do |name|
+          key = name.to_sym
+          [key, normalized_options[key]] if normalized_options.key?(key)
+        end
+
+        next if matches.empty?
+        raise ArgumentError, "Duplicate transformation rule: #{canonical}" if matches.length > 1
+
+        value = normalize_rule(canonical, matches.first.last)
+        present << [canonical, value] unless value.nil?
+      end
+    end
+
+    def normalize_rule(canonical, value)
+      case canonical
+      when 'adjust'
+        normalize_adjust(value)
+      when 'background', 'colorize'
+        normalize_color(value)
+      when 'background_alpha'
+        normalize_number(value, min: 0, max: 1)
+      when 'blur'
+        normalize_true_or_number(value, min: 0.3, max: 100)
+      when 'brightness', 'lightness', 'saturation'
+        normalize_number(value, min: 0.01, max: 10)
+      when 'chroma_subsampling'
+        normalize_enum(value, CHROMA_SUBSAMPLING_VALUES)
+      when 'color_profile'
+        normalize_enum(value, COLOR_PROFILES)
+      when 'contrast'
+        normalize_contrast(value)
+      when 'crop'
+        normalize_crop(value)
+      when 'dpi'
+        normalize_integer(value, min: 1, max: 600)
+      when 'dpr'
+        normalize_number(value, min: 0.01, max: 8)
+      when 'duotone'
+        normalize_duotone(value)
+      when 'enlarge', 'keep_copyright', 'strip_color_profile', 'strip_metadata'
+        normalize_boolean_flag(value)
+      when 'extend'
+        normalize_extend(value)
+      when 'extend_aspect_ratio'
+        normalize_extend_aspect_ratio(value)
+      when 'flip'
+        normalize_flip(value)
+      when 'format'
+        normalize_enum(value, FORMATS)
+      when 'gradient'
+        normalize_gradient(value)
+      when 'gravity'
+        normalize_gravity(value)
+      when 'height', 'min-height', 'min-width', 'width'
+        normalize_integer(value, min: 1, max: 8192)
+      when 'hue'
+        normalize_number(value)
+      when 'monochrome'
+        normalize_monochrome(value)
+      when 'negate'
+        normalize_negate(value)
+      when 'normalize'
+        normalize_normalize(value)
+      when 'padding'
+        normalize_padding(value)
+      when 'pixelate'
+        normalize_integer(value, min: 2, max: 256)
+      when 'progressive'
+        normalize_boolean_or_auto(value)
+      when 'quality'
+        normalize_quality(value)
+      when 'resizing_algorithm'
+        normalize_enum(value, RESIZING_ALGORITHMS)
+      when 'resizing_type'
+        normalize_enum(value, RESIZING_TYPES, aliases: RESIZING_TYPE_ALIASES)
+      when 'rotate', 'watermark_rotate'
+        normalize_rotate(value)
+      when 'sharpen'
+        normalize_sharpen(value)
+      when 'watermark'
+        normalize_watermark(value)
+      when 'watermark_position'
+        normalize_watermark_position(value)
+      when 'watermark_shadow'
+        normalize_watermark_shadow(value)
+      when 'watermark_size'
+        normalize_watermark_size(value)
+      when 'watermark_text'
+        normalize_text_or_json_object(value)
+      when 'watermark_url'
+        normalize_watermark_url(value)
+      when 'zoom'
+        normalize_zoom(value)
+      end
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def normalize_adjust(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      if hash
+        brightness = normalize_number(field(hash, 'brightness'))
+        saturation = normalize_number(field(hash, 'saturation'))
+        color = normalize_number(field(hash, 'color'))
+
+        return contiguous_segments([brightness], [saturation, color])
+      end
+
+      segments = split_segments(value, min: 1, max: 3)
+      return unless segments
+
+      brightness = normalize_number(segments[0])
+      saturation = normalize_number(segments[1]) if segments.length > 1
+      color = normalize_number(segments[2]) if segments.length > 2
+
+      contiguous_segments([brightness], [saturation, color].first(segments.length - 1))
+    end
+
+    def normalize_contrast(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      if hash
+        multiplier = normalize_number(field(hash, 'multiplier'))
+        pivot = normalize_number(field(hash, 'pivot'))
+
+        return contiguous_segments([multiplier], [pivot])
+      end
+
+      segments = split_segments(value, min: 1, max: 2)
+      return unless segments
+
+      multiplier = normalize_number(segments[0])
+      pivot = normalize_number(segments[1]) if segments.length > 1
+
+      contiguous_segments([multiplier], [pivot].first(segments.length - 1))
+    end
+
+    def normalize_crop(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      return normalize_crop_hash(hash) if hash
+
+      segments = split_segments(value, min: 2, max: 5)
+      return unless [2, 3, 4, 5].include?(segments&.length)
+
+      if segments.length <= 3
+        width = normalize_integer(segments[0], min: 1)
+        height = normalize_integer(segments[1], min: 1)
+        gravity = normalize_gravity(segments[2]) if segments.length == 3
+
+        return contiguous_segments([width, height], [gravity].first(segments.length - 2))
+      end
+
+      x = normalize_integer(segments[0])
+      y = normalize_integer(segments[1])
+      width = normalize_integer(segments[2], min: 1)
+      height = normalize_integer(segments[3], min: 1)
+      gravity = normalize_gravity(segments[4]) if segments.length == 5
+
+      contiguous_segments([x, y, width, height], [gravity].first(segments.length - 4))
+    end
+
+    def normalize_crop_hash(hash)
+      x = normalize_integer(field(hash, 'x'))
+      y = normalize_integer(field(hash, 'y'))
+      width = normalize_integer(field(hash, 'width', 'w'), min: 1)
+      height = normalize_integer(field(hash, 'height', 'h'), min: 1)
+      gravity = normalize_gravity(field(hash, 'gravity', 'g'))
+
+      if field?(hash, 'x') || field?(hash, 'y')
+        contiguous_segments([x, y, width, height], [gravity])
+      else
+        contiguous_segments([width, height], [gravity])
+      end
+    end
+
+    def normalize_duotone(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      if hash
+        shadow = normalize_color(field(hash, 'shadowColor', 'shadow_color', 'shadow'))
+        highlight = normalize_color(field(hash, 'highlightColor', 'highlight_color', 'highlight'))
+
+        return contiguous_segments([shadow, highlight], [])
+      end
+
+      segments = split_segments(value, min: 2, max: 2)
+      return unless segments
+
+      shadow = normalize_color(segments[0])
+      highlight = normalize_color(segments[1])
+
+      contiguous_segments([shadow, highlight], [])
+    end
+
+    def normalize_extend(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      return normalize_extend_hash(hash) if hash
+
+      segments = split_segments(value, min: 1, max: 5)
+      return unless segments
+
+      top = normalize_integer(segments[0])
+      right = normalize_integer(segments[1]) if segments.length > 1
+      bottom = normalize_integer(segments[2]) if segments.length > 2
+      left = normalize_integer(segments[3]) if segments.length > 3
+      background = normalize_color(segments[4]) if segments.length > 4
+
+      contiguous_segments([top], [right, bottom, left, background].first(segments.length - 1))
+    end
+
+    def normalize_extend_hash(hash)
+      top = normalize_integer(field(hash, 'top'))
+      right = normalize_integer(field(hash, 'right'))
+      bottom = normalize_integer(field(hash, 'bottom'))
+      left = normalize_integer(field(hash, 'left'))
+      background = normalize_color(field(hash, 'background', 'bg'))
+
+      compact_json = compact_json_object(
+        hash,
+        'top' => top,
+        'right' => right,
+        'bottom' => bottom,
+        'left' => left,
+        'background' => background
+      )
+      return unless compact_json
+
+      contiguous_segments([top], [right, bottom, left, background]) || compact_json
+    end
+
+    def normalize_extend_aspect_ratio(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      if hash
+        ratio = normalize_number(field(hash, 'ratio'), min: 0.000001)
+        return ratio if ratio
+
+        width = normalize_integer(field(hash, 'width', 'w'), min: 1)
+        height = normalize_integer(field(hash, 'height', 'h'), min: 1)
+
+        return contiguous_segments([width, height], [])
+      end
+
+      segments = split_segments(value, min: 1, max: 2)
+      return unless segments
+
+      return normalize_number(segments[0], min: 0.000001) if segments.length == 1
+
+      width = normalize_integer(segments[0], min: 1)
+      height = normalize_integer(segments[1], min: 1)
+
+      contiguous_segments([width, height], [])
+    end
+
+    def normalize_flip(value)
+      hash = value_hash(value)
+      if hash
+        horizontal = parse_boolean(field(hash, 'horizontal'))
+        vertical = parse_boolean(field(hash, 'vertical'))
+        return if horizontal.nil? && vertical.nil?
+
+        return 'both' if horizontal && vertical
+        return 'horizontal' if horizontal
+        return 'vertical' if vertical
+
+        return
+      end
+
+      string = normalize_string(value)
+      return string if FLIP_VALUES.include?(string)
+
+      segments = split_segments(value, min: 2, max: 2)
+      return unless segments
+
+      horizontal = parse_boolean(segments[0])
+      vertical = parse_boolean(segments[1])
+      return if horizontal.nil? || vertical.nil?
+
+      "#{horizontal}:#{vertical}"
+    end
+
+    def normalize_gradient(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      return normalize_gradient_hash(hash) if hash
+
+      segments = split_segments(value, min: 1, max: 4)
+      return unless segments
+
+      colors = normalize_color_list(segments[0])
+      angle = normalize_number(segments[1]) if segments.length > 1
+      opacity = normalize_number(segments[2], min: 0, max: 1) if segments.length > 2
+      blend = normalize_non_empty_string(segments[3]) if segments.length > 3
+
+      contiguous_segments([colors], [angle, opacity, blend].first(segments.length - 1))
+    end
+
+    def normalize_gradient_hash(hash)
+      colors = normalize_color_list(field(hash, 'colors'))
+      angle = normalize_number(field(hash, 'angle'))
+      opacity = normalize_number(field(hash, 'opacity'), min: 0, max: 1)
+      blend = normalize_non_empty_string(field(hash, 'blend'))
+
+      contiguous_segments([colors], [angle, opacity, blend])
+    end
+
+    def normalize_monochrome(value)
+      boolean = parse_boolean(value)
+      return 'true' if boolean == true
+      return if boolean == false
+
+      normalize_color(value)
+    end
+
+    def normalize_negate(value)
+      hash = value_hash(value)
+      if hash
+        alpha = parse_boolean(field(hash, 'alpha'))
+        return unless [true, false].include?(alpha)
+
+        return "alpha:#{alpha}"
+      end
+
+      boolean = parse_boolean(value)
+      return 'true' if boolean == true
+      return if boolean == false
+
+      segments = split_segments(value, min: 2, max: 2)
+      return unless segments&.first == 'alpha'
+
+      alpha = parse_boolean(segments[1])
+      return unless [true, false].include?(alpha)
+
+      "alpha:#{alpha}"
+    end
+
+    def normalize_normalize(value)
+      hash = value_hash(value)
+      if hash
+        lower = normalize_number(field(hash, 'lower'))
+        upper = normalize_number(field(hash, 'upper'))
+
+        return contiguous_segments([lower, upper], [])
+      end
+
+      boolean = parse_boolean(value)
+      return 'true' if boolean == true
+      return if boolean == false
+
+      segments = split_segments(value, min: 2, max: 2)
+      return unless segments
+
+      lower = normalize_number(segments[0])
+      upper = normalize_number(segments[1])
+
+      contiguous_segments([lower, upper], [])
+    end
+
+    def normalize_padding(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      return normalize_padding_hash(hash) if hash
+
+      segments = split_segments(value, min: 1, max: 4)
+      return unless segments
+
+      normalized = segments.map { |segment| normalize_integer(segment) }
+      return if normalized.any?(&:nil?)
+
+      normalized.join(':')
+    end
+
+    def normalize_padding_hash(hash)
+      all = normalize_integer(field(hash, 'all'))
+      return all if all
+
+      x = normalize_integer(field(hash, 'x'))
+      y = normalize_integer(field(hash, 'y'))
+      return contiguous_segments([x, y], []) if x || y
+
+      top = normalize_integer(field(hash, 'top'))
+      right = normalize_integer(field(hash, 'right'))
+      bottom = normalize_integer(field(hash, 'bottom'))
+      left = normalize_integer(field(hash, 'left'))
+
+      compact_json = compact_json_object(
+        hash,
+        'top' => top,
+        'right' => right,
+        'bottom' => bottom,
+        'left' => left
+      )
+      return unless compact_json
+
+      contiguous_segments([top, right, bottom, left], []) || compact_json
+    end
+
+    def normalize_quality(value)
+      return 'auto' if normalize_string(value) == 'auto'
+
+      normalize_integer(value, min: 1, max: 100)
+    end
+
+    def normalize_rotate(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      if hash
+        angle = normalize_number(field(hash, 'angle'))
+        background = normalize_color(field(hash, 'background', 'bg'))
+
+        return contiguous_segments([angle], [background])
+      end
+
+      segments = split_segments(value, min: 1, max: 2)
+      return unless segments
+
+      angle = normalize_number(segments[0])
+      background = normalize_color(segments[1]) if segments.length > 1
+
+      contiguous_segments([angle], [background].first(segments.length - 1))
+    end
+
+    def normalize_sharpen(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      return json_object(hash) if hash
+
+      normalize_true_or_number(value)
+    end
+
+    def normalize_watermark(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      return normalize_watermark_hash(hash) if hash
+
+      segments = split_segments(value, min: 1, max: 4)
+      return unless segments
+
+      image_id = normalize_non_empty_string(segments[0])
+      gravity = normalize_gravity(segments[1]) if segments.length > 1
+      x = normalize_integer(segments[2]) if segments.length > 2
+      y = normalize_integer(segments[3]) if segments.length > 3
+
+      contiguous_segments([image_id], [gravity, x, y].first(segments.length - 1))
+    end
+
+    def normalize_watermark_hash(hash)
+      image_id = normalize_non_empty_string(field(hash, 'image_id', 'imageId', 'id'))
+      gravity = normalize_gravity(field(hash, 'gravity', 'g'))
+      x = normalize_integer(field(hash, 'x'))
+      y = normalize_integer(field(hash, 'y'))
+
+      contiguous_segments([image_id], [gravity, x, y])
+    end
+
+    def normalize_watermark_position(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      return normalize_watermark_position_hash(hash) if hash
+
+      segments = split_segments(value, min: 1, max: 5)
+      return unless segments
+
+      gravity = normalize_gravity(segments[0])
+      x = normalize_integer(segments[1]) if segments.length > 1
+      y = normalize_integer(segments[2]) if segments.length > 2
+      opacity = normalize_number(segments[3], min: 0, max: 1) if segments.length > 3
+      blend = normalize_non_empty_string(segments[4]) if segments.length > 4
+
+      contiguous_segments([gravity], [x, y, opacity, blend].first(segments.length - 1))
+    end
+
+    def normalize_watermark_position_hash(hash)
+      gravity = normalize_gravity(field(hash, 'gravity', 'g'))
+      x = normalize_integer(field(hash, 'x'))
+      y = normalize_integer(field(hash, 'y'))
+      opacity = normalize_number(field(hash, 'opacity'), min: 0, max: 1)
+      blend = normalize_non_empty_string(field(hash, 'blend'))
+
+      contiguous_segments([gravity], [x, y, opacity, blend])
+    end
+
+    def normalize_watermark_shadow(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      boolean = parse_boolean(value)
+      return 'true' if boolean == true
+      return if boolean == false
+
+      hash = value_hash(value)
+      return normalize_watermark_shadow_hash(hash) if hash
+
+      segments = split_segments(value, min: 1, max: 4)
+      return unless segments
+
+      color = normalize_color(segments[0])
+      blur = normalize_number(segments[1]) if segments.length > 1
+      x = normalize_integer(segments[2]) if segments.length > 2
+      y = normalize_integer(segments[3]) if segments.length > 3
+
+      contiguous_segments([color], [blur, x, y].first(segments.length - 1))
+    end
+
+    def normalize_watermark_shadow_hash(hash)
+      color = normalize_color(field(hash, 'color'))
+      blur = normalize_number(field(hash, 'blur'))
+      x = normalize_integer(field(hash, 'x'))
+      y = normalize_integer(field(hash, 'y'))
+
+      contiguous_segments([color], [blur, x, y])
+    end
+
+    def normalize_watermark_size(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      return normalize_watermark_size_hash(hash) if hash
+
+      segments = split_segments(value, min: 1, max: 3)
+      return unless segments
+
+      width = normalize_integer(segments[0], min: 1)
+      height = normalize_integer(segments[1], min: 1) if segments.length > 1
+      scale = normalize_number(segments[2], min: 0.000001) if segments.length > 2
+
+      contiguous_segments([width], [height, scale].first(segments.length - 1))
+    end
+
+    def normalize_watermark_size_hash(hash)
+      width = normalize_integer(field(hash, 'width', 'w'), min: 1)
+      height = normalize_integer(field(hash, 'height', 'h'), min: 1)
+      scale = normalize_number(field(hash, 'scale'), min: 0.000001)
+
+      contiguous_segments([width], [height, scale])
+    end
+
+    def normalize_text_or_json_object(value)
+      return normalize_json_string(value) if json_object_string?(value)
+
+      hash = value_hash(value)
+      return json_object(hash) if hash
+
+      normalize_non_empty_string(value)
+    end
+
+    def normalize_watermark_url(value)
+      string = normalize_non_empty_string(value)
+      return unless string
+
+      return Base64.strict_encode64(string) if valid_https_url?(string)
+
+      string if valid_base64_https_url?(string)
+    end
+
+    def normalize_zoom(value)
+      hash = value_hash(value)
+      if hash
+        factor = normalize_number(field(hash, 'factor'), min: 0.000001)
+        gravity = normalize_gravity(field(hash, 'gravity', 'g'))
+
+        return contiguous_segments([factor], [gravity])
+      end
+
+      segments = split_segments(value, min: 1, max: 2)
+      return unless segments
+
+      factor = normalize_number(segments[0], min: 0.000001)
+      gravity = normalize_gravity(segments[1]) if segments.length > 1
+
+      contiguous_segments([factor], [gravity].first(segments.length - 1))
+    end
+
+    def normalize_top_level_keys(hash)
+      hash.to_h.transform_keys(&:to_sym)
+    end
+
+    def value_hash(value)
+      return unless value.respond_to?(:to_hash)
+
+      value.to_hash.transform_keys(&:to_s)
+    end
+
+    def field(hash, *names)
+      names.each do |name|
+        return hash[name] if hash.key?(name)
+      end
+
+      nil
+    end
+
+    def field?(hash, *names)
+      names.any? { |name| hash.key?(name) }
+    end
+
+    def split_segments(value, min:, max:)
+      string = normalize_non_empty_string(value)
+      return unless string
+
+      segments = string.split(':', -1)
+      return unless segments.length.between?(min, max)
+      return if segments.any?(&:empty?)
+
+      segments
+    end
+
+    def contiguous_segments(required, optional)
+      return if required.any?(&:nil?)
+
+      last_present = optional.rindex { |segment| !segment.nil? }
+      selected_optional = last_present.nil? ? [] : optional[0..last_present]
+      return if selected_optional.any?(&:nil?)
+
+      (required + selected_optional).join(':')
+    end
+
+    def normalize_boolean_flag(value)
+      parse_boolean(value) == true ? 'true' : nil
+    end
+
+    def normalize_boolean_or_auto(value)
+      return 'auto' if normalize_string(value) == 'auto'
+
+      boolean = parse_boolean(value)
+      return 'true' if boolean == true
+
+      'false' if boolean == false
+    end
+
+    def parse_boolean(value)
+      return true if value == true
+      return false if value == false
+      return true if value == 1
+      return false if value.is_a?(Numeric) && value.zero?
+
+      case normalize_string(value)
+      when 'true', '1'
+        true
+      when 'false', '0'
+        false
+      end
+    end
+
+    def normalize_true_or_number(value, min: nil, max: nil)
+      boolean = parse_boolean(value)
+      return 'true' if boolean == true
+      return if boolean == false
+
+      normalize_number(value, min: min, max: max)
+    end
+
+    def normalize_integer(value, min: nil, max: nil)
+      integer = parse_integer(value)
+      return if integer.nil?
+      return if min && integer < min
+      return if max && integer > max
+
+      integer.to_s
+    end
+
+    def parse_integer(value)
+      return value if value.is_a?(Integer)
+
+      if value.is_a?(Float)
+        return unless value.finite? && value == value.to_i
+
+        return value.to_i
+      end
+
+      string = normalize_non_empty_string(value)
+      return unless string&.match?(/\A[+-]?\d+\z/)
+
+      Integer(string)
+    end
+
+    def normalize_number(value, min: nil, max: nil)
+      number = parse_number(value)
+      return if number.nil?
+      return if min && number < min
+      return if max && number > max
+
+      format_number(number)
+    end
+
+    def parse_number(value)
+      return value.to_f if value.is_a?(Numeric) && value.to_f.finite?
+
+      string = normalize_non_empty_string(value)
+      return unless string
+
+      number = Float(string)
+      return unless number.finite?
+
+      number
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def format_number(number)
+      return number.to_i.to_s if number == number.to_i
+
+      number.to_s
+    end
+
+    def normalize_enum(value, values, aliases: {})
+      string = normalize_string(value)
+      return aliases[string] if aliases.key?(string)
+
+      string if values.include?(string)
+    end
+
+    def normalize_gravity(value)
+      string = normalize_string(value)
+      return GRAVITY_ALIASES[string] if GRAVITY_ALIASES.key?(string)
+
+      string if GRAVITY_VALUES.include?(string)
+    end
+
+    def normalize_color(value)
+      string = normalize_non_empty_string(value)
+      return unless string
+
+      string = string.delete_prefix('#')
+      return string.downcase if string.match?(/\A(?:[[:xdigit:]]{3}|[[:xdigit:]]{6}|[[:xdigit:]]{8})\z/)
+
+      string if rgb_color?(string)
+    end
+
+    def rgb_color?(string)
+      segments = string.split(':', -1)
+      return false unless [3, 4].include?(segments.length)
+
+      red, green, blue = segments.first(3).map { |segment| parse_integer(segment) }
+      return false unless [red, green, blue].all? { |part| part&.between?(0, 255) }
+      return true if segments.length == 3
+
+      alpha = parse_number(segments[3])
+      alpha&.between?(0, 1)
+    end
+
+    def normalize_color_list(value)
+      colors = value.is_a?(Array) ? value : normalize_non_empty_string(value)&.split(',', -1)
+      return unless colors&.length&.>= 2
+
+      normalized = colors.map { |color| normalize_color(color) }
+      return if normalized.any?(&:nil?)
+
+      normalized.join(',')
+    end
+
+    def normalize_non_empty_string(value)
+      string = value.to_s.strip
+      return if string.empty?
+
+      string
+    end
+
+    def normalize_string(value)
+      normalize_non_empty_string(value)&.downcase
+    end
+
+    def json_object_string?(value)
+      string = normalize_non_empty_string(value)
+      return false unless string&.start_with?('{')
+
+      JSON.parse(string).is_a?(Hash)
+    rescue JSON::ParserError
+      false
+    end
+
+    def normalize_json_string(value)
+      normalize_non_empty_string(value)
+    end
+
+    def compact_json_object(input_hash, fields)
+      return unless fields.values.any?
+      return if fields.any? { |key, item| field?(input_hash, key) && item.nil? }
+
+      JSON.generate(fields.compact)
+    end
+
+    def json_object(hash)
+      return if hash.empty?
+
+      JSON.generate(camelize_hash_keys(hash))
+    end
+
+    def camelize_hash_keys(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        result[camelize_key(key)] = value.is_a?(Hash) ? camelize_hash_keys(value) : value
+      end
+    end
+
+    def camelize_key(key)
+      key.to_s.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+    end
+
+    def valid_https_url?(value)
+      uri = URI.parse(value)
+      uri.is_a?(URI::HTTPS) && uri.host && !uri.host.empty?
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def valid_base64_https_url?(value)
+      decoded = Base64.strict_decode64(value)
+      valid_https_url?(decoded)
+    rescue ArgumentError
+      false
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/imgwire/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imgwire
-  VERSION = '0.2.0'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imgwire
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Blackhawk Software, LLC
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-18 00:00:00.000000000 Z
+date: 2026-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -130,6 +144,7 @@ files:
 - lib/imgwire/resources/images_resource.rb
 - lib/imgwire/resources/metrics_resource.rb
 - lib/imgwire/uploads.rb
+- lib/imgwire/url_transformations.rb
 - lib/imgwire/version.rb
 homepage: https://github.com/Blackhawk-Software/imgwire-ruby
 licenses: