cloudinary 1.25.0 → 1.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27739f4540fd5b75d22128cc2bb0d885160c4d00163e658048ef770e72ab2d33
-  data.tar.gz: e4f02a3ce402b625a1323f6e0cc14d8f55436de953127090491266377d9576e9
+  metadata.gz: 46b21a3d7dd2411acaaeb35016f2ff7b648aeae5c1d077870f38e858ce1abedf
+  data.tar.gz: 5825bea0988e97e71df1d93fde04739b502230cda987f90415cb46f55df8b6b7
 SHA512:
-  metadata.gz: 15e356e735c9c9e7a2cf0df6269e553bff2e4416386cfdff9a3d5edc81d6fbd4213c73d4c6e907e6a42e8d3680dcbf74e4d90ded012d7ed1c8167a2271ab251f
-  data.tar.gz: 2720b423770f63dbb7369233c12096846fa157ba2f0f4f465da94128bd574bdc2992bfba8a89ee81877e571a26fbd33a86b6150cfccb78923bd9d2267c9f0b08
+  metadata.gz: 24c1334398c9c24ce9b0b536e991fb76aa633e1bda93b5e8dcccc1d2ac2f747e4645f52b61ad3b6db7bb9a59a092df602c35b964a05661c151fb6026cd1954c0
+  data.tar.gz: f8f3cdbe7b7374532f5dae2f5dca3543697a2fb2398050b4a7874d6527b3e87ffc84970684aefe25c65f255ba9ec89e15470e28658c28287df781e4ee2144799

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+1.27.0 / 2023-07-31
+==================
+
+New functionality and features
+------------------------------
+
+  * Add support for `visual_search` Admin API
+  * Add support for Search URL
+  * Add support for `SearchFolders` API
+  * Add support for `media_metadata` API parameter
+
+1.26.0 / 2023-06-01
+==================
+
+New functionality and features
+------------------------------
+
+  * Add support for related assets Admin APIs
+  * Add support for expressions in `start_offset` and `end_offset` parameters
+  * Add support for Conditional Metadata Rules API
+  * Add support for large files in Active Storage
+
 1.25.0 / 2023-01-04
 ==================
 

data/cloudinary.gemspec

@@ -39,8 +39,12 @@ Gem::Specification.new do |s|
   else
     s.add_development_dependency "rake", "<= 12.2.1"
   end
+  if RUBY_VERSION >= "2.7.0"
+    s.add_development_dependency "sqlite3"
+  else
+    s.add_development_dependency "sqlite3", "< 1.6.0"
+  end
 
-  s.add_development_dependency "sqlite3"
   s.add_development_dependency "rspec", '>=3.5'
   s.add_development_dependency "rspec-retry"
 
@@ -57,6 +61,8 @@ Gem::Specification.new do |s|
 
   if RUBY_VERSION <= "2.4.0"
     s.add_development_dependency "simplecov", "<= 0.17.1" # support testing Ruby 1.9
+    s.add_development_dependency 'loofah', '~>2.19.1'
+    s.add_development_dependency "rails-html-sanitizer", "<1.5.0"
   else
     s.add_development_dependency "simplecov", "> 0.18.0"
   end

data/lib/active_storage/service/cloudinary_service.rb

@@ -39,7 +39,7 @@ module ActiveStorage
         begin
           extra_headers = checksum.nil? ? {} : {Headers::CONTENT_MD5 => checksum}
           options = @options.merge(options)
-          Cloudinary::Uploader.upload(
+          Cloudinary::Uploader.upload_large(
             io,
             public_id: public_id_internal(key),
             resource_type: resource_type(io, key),

data/lib/cloudinary/api.rb

@@ -207,6 +207,19 @@ class Cloudinary::Api
     call_api(:get, uri, params, options)
   end
 
+  # Find images based on their visual content.
+  #
+  # @param [Hash]   options      The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  def self.visual_search(options = {})
+    uri    = "resources/visual_search"
+    params = only(options, :image_url, :image_asset_id, :text)
+    call_api(:get, uri, params, options)
+  end
+
   # Returns the details of the specified asset and all its derived assets.
   #
   # Note that if you only need details about the original asset,
@@ -406,6 +419,76 @@ class Cloudinary::Api
     call_api(:delete, uri, params, options)
   end
 
+  # Relates an asset to other assets by public IDs.
+  #
+  # @param [String]            public_id        The public ID of the asset.
+  # @param [String|Array]      assets_to_relate The array of up to 10 fully_qualified_public_ids given as
+  #                                             resource_type/type/public_id.
+  # @param [Hash]              options          The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#add_related_assets Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  def self.add_related_assets(public_id, assets_to_relate, options={})
+    resource_type = options[:resource_type] || "image"
+    type          = options[:type] || "upload"
+    uri           = "resources/related_assets/#{resource_type}/#{type}/#{public_id}"
+    params = {:assets_to_relate => Cloudinary::Utils.build_array(assets_to_relate)}
+    call_api(:post, uri, params, options)
+  end
+
+  # Relates an asset to other assets by asset IDs.
+  #
+  # @param [String]            asset_id         The asset ID of the asset to update.
+  # @param [String|Array]      assets_to_relate The array of up to 10 asset IDs.
+  # @param [Hash]              options          The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#add_related_assets_by_asset_id Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  def self.add_related_assets_by_asset_ids(asset_id, assets_to_relate, options={})
+    uri           = "resources/related_assets/#{asset_id}"
+    params = {:assets_to_relate => Cloudinary::Utils.build_array(assets_to_relate)}
+    call_api(:post, uri, params, options)
+  end
+
+  # Unrelates an asset from other assets by public IDs.
+  #
+  # @param [String]            public_id          The public ID of the asset.
+  # @param [String|Array]      assets_to_unrelate The array of up to 10 fully_qualified_public_ids given as
+  #                                               resource_type/type/public_id.
+  # @param [Hash]              options            The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#delete_related_assets Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  def self.delete_related_assets(public_id, assets_to_unrelate, options={})
+    resource_type = options[:resource_type] || "image"
+    type          = options[:type] || "upload"
+    uri           = "resources/related_assets/#{resource_type}/#{type}/#{public_id}"
+    params = {:assets_to_unrelate => Cloudinary::Utils.build_array(assets_to_unrelate)}
+    call_api(:delete, uri, params, options)
+  end
+
+  # Unrelates an asset from other assets by asset IDs.
+  #
+  # @param [String]            asset_id           The asset ID of the asset to update.
+  # @param [String|Array]      assets_to_unrelate The array of up to 10 asset IDs.
+  # @param [Hash]              options            The optional parameters. See the
+  #   {https://cloudinary.com/documentation/admin_api#delete_related_assets_by_asset_id Admin API} documentation.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  def self.delete_related_assets_by_asset_ids(asset_id, assets_to_unrelate, options={})
+    uri           = "resources/related_assets/#{asset_id}"
+    params = {:assets_to_unrelate => Cloudinary::Utils.build_array(assets_to_unrelate)}
+    call_api(:delete, uri, params, options)
+  end
+
   # Lists all the tags currently used for a specified asset type.
   #
   # @param [Hash] options The optional parameters. See the
@@ -1077,6 +1160,75 @@ class Cloudinary::Api
     call_metadata_api(:put, uri, params, options)
   end
 
+  # Lists all metadata rules definitions.
+  #
+  # @param [Hash] options The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/conditional_metadata_rules_api#get_metadata_rules
+  def self.list_metadata_rules(options = {})
+    call_metadata_rules_api(:get, [], {}, options)
+  end
+
+
+  # Creates a new metadata rule definition.
+  #
+  # @param [Hash] rule    The rule to add.
+  # @param [Hash] options The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/conditional_metadata_rules_api#create_a_metadata_rule
+  def self.add_metadata_rule(rule, options = {})
+    params = only(rule, :metadata_field_id, :condition, :result, :name)
+
+    call_metadata_rules_api(:post, [], params, options)
+  end
+
+  # Updates a metadata rule by external ID.
+  #
+  # Updates an existing metadata rule definition. Expects a JSON object which defines the updated rule.
+  #
+  # @param [String] external_id       The ID of the rule to update.
+  # @param [Hash]   rule              The rule definition.
+  # @param [Hash]   options           The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/conditional_metadata_rules_api#update_a_metadata_rule_by_id
+  def self.update_metadata_rule(external_id, rule, options = {})
+    uri = [external_id]
+    params = only(rule, :metadata_field_id, :condition, :result, :name, :state)
+
+    call_metadata_rules_api(:put, uri, params, options)
+  end
+
+  # Deletes a metadata rule definition by external ID.
+  #
+  # The rule should no longer be considered a valid candidate for all other endpoints
+  # (it will not show up in the list of rules, etc).
+  #
+  # @param [String] external_id The ID of the rule to delete.
+  # @param [Hash]   options     The optional parameters.
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  #
+  # @see https://cloudinary.com/documentation/conditional_metadata_rules_api#delete_a_metadata_rule_by_id
+  def self.delete_metadata_rule(external_id, options = {})
+    uri = [external_id]
+
+    call_metadata_rules_api(:delete, uri, {}, options)
+  end
+
   protected
 
   # Execute a call api for input params.
@@ -1128,6 +1280,22 @@ class Cloudinary::Api
     call_api(method, uri, params, options)
   end
 
+  # Protected function that assists with performing an API call to the metadata_rules part of the Admin API.
+  #
+  # @protected
+  # @param [Symbol] method  The HTTP method. Valid methods: get, post, put, delete
+  # @param [Array]  uri     REST endpoint of the API (without 'metadata_rules')
+  # @param [Hash]   params  Query/body parameters passed to the method
+  # @param [Hash]   options Additional options. Can be an override of the configuration, headers, etc.
+  # @return [Cloudinary::Api::Response] Returned response from Cloudinary
+  # @raise [Cloudinary::Api::Error]
+  def self.call_metadata_rules_api(method, uri, params, options)
+    options[:content_type] = :json
+    uri = ["metadata_rules", uri].reject(&:empty?).join("/")
+
+    call_api(method, uri, params, options)
+  end
+
   # Prepares optional parameters for asset/assetByAssetId API calls.
   # @param  [Hash]   options Additional options
   # @return [Object]         Optional parameters
@@ -1138,6 +1306,7 @@ class Cloudinary::Api
          :faces,
          :quality_analysis,
          :image_metadata,
+         :media_metadata,
          :phash,
          :pages,
          :cinemagraph_analysis,

data/lib/cloudinary/search.rb

@@ -1,15 +1,23 @@
 class Cloudinary::Search
+  ENDPOINT = 'resources'
+
   SORT_BY    = :sort_by
   AGGREGATE  = :aggregate
   WITH_FIELD = :with_field
   KEYS_WITH_UNIQUE_VALUES = [SORT_BY, AGGREGATE, WITH_FIELD].freeze
 
+  TTL = 300 # Used for search URLs
+
   def initialize
     @query_hash = {
       SORT_BY    => {},
       AGGREGATE  => {},
       WITH_FIELD => {}
     }
+
+    @endpoint = self.class::ENDPOINT
+
+    @ttl = self.class::TTL
   end
 
   ## implicitly generate an instance delegate the method
@@ -69,11 +77,21 @@ class Cloudinary::Search
     self
   end
 
+  # Sets the time to live of the search URL.
+  #
+  # @param [Object] ttl The time to live in seconds.
+  #
+  # @return [Cloudinary::Search]
+  def ttl(ttl)
+    @ttl = ttl
+    self
+  end
+
   # Returns the query as an hash.
   #
   # @return [Hash]
   def to_h
-    @query_hash.each_with_object({}) do |(key, value), query|
+    @query_hash.sort.each_with_object({}) do |(key, value), query|
       next if value.nil? || ((value.is_a?(Array) || value.is_a?(Hash)) && value.blank?)
 
       query[key] = KEYS_WITH_UNIQUE_VALUES.include?(key) ? value.values : value
@@ -82,7 +100,44 @@ class Cloudinary::Search
 
   def execute(options = {})
     options[:content_type] = :json
-    uri = 'resources/search'
+    uri = "#{@endpoint}/search"
     Cloudinary::Api.call_api(:post, uri, to_h, options)
   end
+
+  # Creates a signed Search URL that can be used on the client side.
+  #
+  # @param [Integer] ttl The time to live in seconds.
+  # @param [String] next_cursor Starting position.
+  # @param [Hash] options Additional url delivery options.
+  #
+  # @return [String] The resulting Search URL
+  def to_url(ttl = nil, next_cursor = nil, options = {})
+    api_secret = options[:api_secret] || Cloudinary.config.api_secret || raise(CloudinaryException, "Must supply api_secret")
+
+    ttl   = ttl || @ttl
+    query = self.to_h
+
+    _next_cursor = query.delete(:next_cursor)
+    next_cursor  = _next_cursor if next_cursor.nil?
+
+    b64query = Base64.urlsafe_encode64(JSON.generate(query))
+
+    prefix = Cloudinary::Utils.build_distribution_domain(options)
+
+    signature = Cloudinary::Utils.hash("#{ttl}#{b64query}#{api_secret}", :sha256, :hexdigest)
+
+    next_cursor = "/#{next_cursor}" if !next_cursor.nil? && !next_cursor.empty?
+
+    "#{prefix}/search/#{signature}/#{ttl}/#{b64query}#{next_cursor}"
+  end
+
+  # Sets the API endpoint.
+  #
+  # @param [String] endpoint the endpoint to set.
+  #
+  # @return [Cloudinary::Search]
+  def endpoint(endpoint)
+    @endpoint = endpoint
+    self
+  end
 end

data/lib/cloudinary/search_folders.rb

@@ -0,0 +1,5 @@
+# The Cloudinary API folders search method allows you fine control on filtering and retrieving information on all the
+# folders in your cloud with the help of query expressions in a Lucene-like query language.
+class Cloudinary::SearchFolders < Cloudinary::Search
+  ENDPOINT = 'folders'
+end

data/lib/cloudinary/uploader.rb

@@ -47,6 +47,7 @@ class Cloudinary::Uploader
       :filename_override                    => options[:filename_override],
       :headers                              => build_custom_headers(options[:headers]),
       :image_metadata                       => Cloudinary::Utils.as_safe_bool(options[:image_metadata]),
+      :media_metadata                       => Cloudinary::Utils.as_safe_bool(options[:media_metadata]),
       :invalidate                           => Cloudinary::Utils.as_safe_bool(options[:invalidate]),
       :moderation                           => options[:moderation],
       :notification_url                     => options[:notification_url],
@@ -62,6 +63,7 @@ class Cloudinary::Uploader
       :responsive_breakpoints               => Cloudinary::Utils.generate_responsive_breakpoints_string(options[:responsive_breakpoints]),
       :return_delete_token                  => Cloudinary::Utils.as_safe_bool(options[:return_delete_token]),
       :similarity_search                    => options[:similarity_search],
+      :visual_search                        => Cloudinary::Utils.as_safe_bool(options[:visual_search]),
       :tags                                 => options[:tags] && Cloudinary::Utils.build_array(options[:tags]).join(","),
       :timestamp                            => (options[:timestamp] || Time.now.to_i),
       :transformation                       => Cloudinary::Utils.generate_transformation_string(options.clone),
@@ -108,26 +110,38 @@ class Cloudinary::Uploader
       public_id = public_id_or_options
       options   = old_options
     end
+
+    options.merge(:public_id => public_id)
+
     if Cloudinary::Utils.is_remote?(file)
-      return upload(file, options.merge(:public_id => public_id))
-    elsif file.is_a?(Pathname) || !file.respond_to?(:read)
+      return upload(file, options)
+    end
+
+    if file.is_a?(Pathname) || !file.respond_to?(:read)
       filename = file
       file     = File.open(file, "rb")
     else
       filename = "cloudinaryfile"
     end
 
+    chunk_size = options[:chunk_size] || 20_000_000
+
+    if file.size < chunk_size
+      return upload(file, options)
+    end
+
     filename = options[:filename] if options[:filename]
 
     unique_upload_id = Cloudinary::Utils.random_public_id
     upload     = nil
     index      = 0
-    chunk_size = options[:chunk_size] || 20_000_000
+
     until file.eof?
       buffer      = file.read(chunk_size)
       current_loc = index*chunk_size
       range       = "bytes #{current_loc}-#{current_loc+buffer.size - 1}/#{file.size}"
-      upload      = upload_large_part(Cloudinary::Blob.new(buffer, :original_filename => filename), options.merge(:public_id => public_id, :unique_upload_id => unique_upload_id, :content_range => range))
+      upload      = upload_large_part(Cloudinary::Blob.new(buffer, :original_filename => filename),
+                                      options.merge(:unique_upload_id => unique_upload_id, :content_range => range))
       index       += 1
     end
     upload

data/lib/cloudinary/utils.rb

@@ -524,18 +524,10 @@ class Cloudinary::Utils
     version = options.delete(:version)
     force_version = config_option_consume(options, :force_version, true)
     format = options.delete(:format)
-    cloud_name = config_option_consume(options, :cloud_name) || raise(CloudinaryException, "Must supply cloud_name in tag or in configuration")
 
-    secure = options.delete(:secure)
-    ssl_detected = options.delete(:ssl_detected)
-    secure = ssl_detected || Cloudinary.config.secure if secure.nil?
-    private_cdn = config_option_consume(options, :private_cdn)
-    secure_distribution = config_option_consume(options, :secure_distribution)
-    cname = config_option_consume(options, :cname)
     shorten = config_option_consume(options, :shorten)
     force_remote = options.delete(:force_remote)
-    cdn_subdomain = config_option_consume(options, :cdn_subdomain)
-    secure_cdn_subdomain = config_option_consume(options, :secure_cdn_subdomain)
+
     sign_url = config_option_consume(options, :sign_url)
     secret = config_option_consume(options, :api_secret)
     sign_version = config_option_consume(options, :sign_version) # Deprecated behavior
@@ -558,7 +550,7 @@ class Cloudinary::Utils
     type = type.to_s unless type.nil?
     resource_type ||= "image"
     source = source.to_s
-    if !force_remote
+    unless force_remote
       static_support = Cloudinary.config.static_file_support || Cloudinary.config.static_image_support
       return original_source if !static_support && type == "asset"
       return original_source if (type.nil? || type == "asset") && source.match(%r(^https?:/)i)
@@ -594,7 +586,9 @@ class Cloudinary::Utils
       signature = "s--#{signature[0, long_url_signature ? LONG_URL_SIGNATURE_LENGTH : SHORT_URL_SIGNATURE_LENGTH ]}--"
     end
 
-    prefix = unsigned_download_url_prefix(source, cloud_name, private_cdn, cdn_subdomain, secure_cdn_subdomain, cname, secure, secure_distribution)
+    options[:source] = source
+    prefix = build_distribution_domain(options)
+
     source = [prefix, resource_type, type, signature, transformation, version, source].reject(&:blank?).join("/")
     if sign_url && auth_token && !auth_token.empty?
       auth_token[:url] = URI.parse(source).path
@@ -707,6 +701,22 @@ class Cloudinary::Utils
     prefix
   end
 
+  def self.build_distribution_domain(options = {})
+    cloud_name = config_option_consume(options, :cloud_name) || raise(CloudinaryException, "Must supply cloud_name in tag or in configuration")
+
+    source = options.delete(:source)
+    secure = options.delete(:secure)
+    ssl_detected = options.delete(:ssl_detected)
+    secure = ssl_detected || Cloudinary.config.secure if secure.nil?
+    private_cdn = config_option_consume(options, :private_cdn)
+    secure_distribution = config_option_consume(options, :secure_distribution)
+    cname = config_option_consume(options, :cname)
+    cdn_subdomain = config_option_consume(options, :cdn_subdomain)
+    secure_cdn_subdomain = config_option_consume(options, :secure_cdn_subdomain)
+
+    unsigned_download_url_prefix(source, cloud_name, private_cdn, cdn_subdomain, secure_cdn_subdomain, cname, secure, secure_distribution)
+  end
+
   # Creates a base URL for the cloudinary api
   #
   # @param [Object] path  Resource name
@@ -1175,11 +1185,13 @@ class Cloudinary::Utils
   # @private
   def self.norm_range_value(value) # :nodoc:
     offset = /^#{offset_any_pattern}$/.match( value.to_s)
+
     if offset
-      modifier   = offset[5].present? ? 'p' : ''
-      value  = "#{offset[1]}#{modifier}"
+      modifier = offset[5].present? ? 'p' : ''
+      "#{offset[1]}#{modifier}"
+    else
+      normalize_expression(value)
     end
-    value
   end
   private_class_method :norm_range_value
 
@@ -1371,6 +1383,4 @@ class Cloudinary::Utils
     algorithm = ALGORITHM_SIGNATURE[signature_algorithm] || raise("Unsupported algorithm '#{signature_algorithm}'")
     algorithm.public_send(hash_method, input)
   end
-
-  private_class_method :hash
 end

data/lib/cloudinary/version.rb

@@ -1,4 +1,4 @@
 # Copyright Cloudinary
 module Cloudinary
-  VERSION = "1.25.0"
+  VERSION = "1.27.0"
 end

data/lib/cloudinary.rb

@@ -28,6 +28,7 @@ module Cloudinary
   autoload :Static, "cloudinary/static"
   autoload :CarrierWave, "cloudinary/carrier_wave"
   autoload :Search, "cloudinary/search"
+  autoload :SearchFolders, "cloudinary/search_folders"
 
   CF_SHARED_CDN         = "d3jpl91pxevbkh.cloudfront.net"
   AKAMAI_SHARED_CDN     = "res.cloudinary.com"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cloudinary
 version: !ruby/object:Gem::Version
-  version: 1.25.0
+  version: 1.27.0
 platform: ruby
 authors:
 - Nadav Soferman
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-04 00:00:00.000000000 Z
+date: 2023-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws_cf_signer
@@ -235,6 +235,7 @@ files:
 - lib/cloudinary/railtie.rb
 - lib/cloudinary/responsive.rb
 - lib/cloudinary/search.rb
+- lib/cloudinary/search_folders.rb
 - lib/cloudinary/static.rb
 - lib/cloudinary/uploader.rb
 - lib/cloudinary/utils.rb
@@ -276,8 +277,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: cloudinary
-rubygems_version: 2.7.6
+rubygems_version: 3.4.12
 signing_key: 
 specification_version: 4
 summary: Client library for easily using the Cloudinary service