cloudinary 1.20.0 → 1.23.0

data/lib/cloudinary/auth_token.rb

@@ -21,7 +21,12 @@ module Cloudinary
       start = options[:start_time]
       expiration = options[:expiration]
       ip = options[:ip]
+
       acl = options[:acl]
+      if acl.present?
+        acl = acl.is_a?(String) ? [acl] : acl
+      end
+
       duration = options[:duration]
       url = options[:url]
       start = Time.new.getgm.to_i if start == 'now'
@@ -41,9 +46,9 @@ module Cloudinary
       token << "ip=#{ip}" if ip
       token << "st=#{start}" if start
       token << "exp=#{expiration}"
-      token << "acl=#{escape_to_lower(acl)}" if acl
+      token << "acl=#{escape_to_lower(acl.join('!'))}" if acl && acl.size > 0
       to_sign = token.clone
-      to_sign << "url=#{escape_to_lower(url)}" if url
+      to_sign << "url=#{escape_to_lower(url)}" if url && (acl.blank? || acl.size == 0)
       auth = digest(to_sign.join(SEPARATOR), key)
       token << "hmac=#{auth}"
       "#{name}=#{token.join(SEPARATOR)}"

data/lib/cloudinary/base_api.rb

@@ -19,9 +19,12 @@ module Cloudinary::BaseApi
         # This sets the instantiated self as the response Hash
         update Cloudinary::Api.parse_json_response response
 
-        @rate_limit_allowed   = response.headers[:x_featureratelimit_limit].to_i if response.headers[:x_featureratelimit_limit]
-        @rate_limit_reset_at  = Time.parse(response.headers[:x_featureratelimit_reset]) if response.headers[:x_featureratelimit_reset]
-        @rate_limit_remaining = response.headers[:x_featureratelimit_remaining].to_i if response.headers[:x_featureratelimit_remaining]
+        # According to RFC 2616, header names are case-insensitive.
+        lc_headers = response.headers.transform_keys(&:downcase)
+
+        @rate_limit_allowed   = lc_headers[:x_featureratelimit_limit].to_i if lc_headers[:x_featureratelimit_limit]
+        @rate_limit_reset_at  = Time.parse(lc_headers[:x_featureratelimit_reset]) if lc_headers[:x_featureratelimit_reset]
+        @rate_limit_remaining = lc_headers[:x_featureratelimit_remaining].to_i if lc_headers[:x_featureratelimit_remaining]
       end
     end
   end
@@ -59,13 +62,14 @@ module Cloudinary::BaseApi
 
   private
 
-  def call_cloudinary_api(method, uri, user, password, params, options, &api_url_builder)
+  def call_cloudinary_api(method, uri, auth, params, options, &api_url_builder)
     cloudinary = options[:upload_prefix] || Cloudinary.config.upload_prefix || 'https://api.cloudinary.com'
     api_url    = Cloudinary::Utils.smart_escape(api_url_builder.call(cloudinary, uri).flatten.join('/'))
     timeout    = options[:timeout] || Cloudinary.config.timeout || 60
     proxy      = options[:api_proxy] || Cloudinary.config.api_proxy
 
     headers = { "User-Agent" => Cloudinary::USER_AGENT }
+    headers.merge!("Authorization" => get_authorization_header_value(auth))
 
     if options[:content_type] == :json
       payload = params.to_json
@@ -74,6 +78,21 @@ module Cloudinary::BaseApi
       payload = params.reject { |_, v| v.nil? || v == "" }
     end
 
-    call_json_api(method, api_url, payload, timeout, headers, proxy, user, password)
+    call_json_api(method, api_url, payload, timeout, headers, proxy)
+  end
+
+  def get_authorization_header_value(auth)
+    if auth[:oauth_token].present?
+      "Bearer #{auth[:oauth_token]}"
+    else
+      "Basic #{Base64.urlsafe_encode64("#{auth[:key]}:#{auth[:secret]}")}"
+    end
+  end
+
+  def validate_authorization(api_key, api_secret, oauth_token)
+    return if oauth_token.present?
+
+    raise("Must supply api_key") if api_key.nil?
+    raise("Must supply api_secret") if api_secret.nil?
   end
 end

data/lib/cloudinary/carrier_wave/process.rb

@@ -154,8 +154,16 @@ module Cloudinary::CarrierWave
     format = Cloudinary::PreloadedFile.split_format(original_filename || "").last
     return format || "" if resource_type == "raw"
     format = requested_format || format || default_format
- 
+
     format = format.to_s.downcase
     Cloudinary::FORMAT_ALIASES[format] || format
   end
+
+  def store!(new_file=nil)
+    super
+
+    column = model.send(:_mounter, mounted_as).send(:serialization_column)
+    identifier = model.send(:attribute, column)
+    retrieve_from_store!(identifier) unless identifier.nil?
+  end
 end

data/lib/cloudinary/search.rb

@@ -1,9 +1,14 @@
 class Cloudinary::Search
+  SORT_BY    = :sort_by
+  AGGREGATE  = :aggregate
+  WITH_FIELD = :with_field
+  KEYS_WITH_UNIQUE_VALUES = [SORT_BY, AGGREGATE, WITH_FIELD].freeze
+
   def initialize
     @query_hash = {
-      :sort_by    => [],
-      :aggregate  => [],
-      :with_field   => []
+      SORT_BY    => {},
+      AGGREGATE  => {},
+      WITH_FIELD => {}
     }
   end
 
@@ -28,23 +33,51 @@ class Cloudinary::Search
     self
   end
 
+  # Sets the `sort_by` field.
+  #
+  # @param [String] field_name   The field to sort by. You can specify more than one sort_by parameter;
+  #                              results will be sorted according to the order of the fields provided.
+  # @param [String] dir          Sort direction. Valid sort directions are 'asc' or 'desc'. Default: 'desc'.
+  #
+  # @return [Cloudinary::Search]
   def sort_by(field_name, dir = 'desc')
-    @query_hash[:sort_by].push(field_name => dir)
+    @query_hash[SORT_BY][field_name] = { field_name => dir }
     self
   end
 
+  # The name of a field (attribute) for which an aggregation count should be calculated and returned in the response.
+  #
+  # You can specify more than one aggregate parameter.
+  #
+  # @param [String] value  Supported values: resource_type, type, pixels (only the image assets in the response are
+  #                        aggregated), duration (only the video assets in the response are aggregated), format, and
+  #                        bytes. For aggregation fields without discrete values, the results are divided into 
+  #                        categories.
+  # @return [Cloudinary::Search]
   def aggregate(value)
-    @query_hash[:aggregate].push(value)
+    @query_hash[AGGREGATE][value] = value
     self
   end
 
+  # The name of an additional asset attribute to include for each asset in the response.
+  #
+  # @param [String] value Possible value: context, tags, and for Tier 2 also image_metadata, and image_analysis.
+  #
+  # @return [Cloudinary::Search]
   def with_field(value)
-    @query_hash[:with_field].push(value)
+    @query_hash[WITH_FIELD][value] = value
     self
   end
 
+  # Returns the query as an hash.
+  #
+  # @return [Hash]
   def to_h
-    @query_hash.select { |_, value| !value.nil? && !(value.is_a?(Array) && value.empty?) }
+    @query_hash.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
+    end
   end
 
   def execute(options = {})

data/lib/cloudinary/uploader.rb

@@ -21,6 +21,7 @@ class Cloudinary::Uploader
       :access_control            => Cloudinary::Utils.json_array_param(options[:access_control]),
       :access_mode               => options[:access_mode],
       :allowed_formats           => Cloudinary::Utils.build_array(options[:allowed_formats]).join(","),
+      :asset_folder              => options[:asset_folder],
       :async                     => Cloudinary::Utils.as_safe_bool(options[:async]),
       :auto_tagging              => options[:auto_tagging] && options[:auto_tagging].to_f,
       :background_removal        => options[:background_removal],
@@ -33,6 +34,7 @@ class Cloudinary::Uploader
       :custom_coordinates        => Cloudinary::Utils.encode_double_array(options[:custom_coordinates]),
       :detection                 => options[:detection],
       :discard_original_filename => Cloudinary::Utils.as_safe_bool(options[:discard_original_filename]),
+      :display_name              => options[:display_name],
       :eager                     => Cloudinary::Utils.build_eager(options[:eager]),
       :eager_async               => Cloudinary::Utils.as_safe_bool(options[:eager_async]),
       :eager_notification_url    => options[:eager_notification_url],
@@ -53,6 +55,7 @@ class Cloudinary::Uploader
       :phash                     => Cloudinary::Utils.as_safe_bool(options[:phash]),
       :proxy                     => options[:proxy],
       :public_id                 => options[:public_id],
+      :public_id_prefix          => options[:public_id_prefix],
       :quality_analysis          => Cloudinary::Utils.as_safe_bool(options[:quality_analysis]),
       :quality_override          => options[:quality_override],
       :raw_convert               => options[:raw_convert],
@@ -66,6 +69,7 @@ class Cloudinary::Uploader
       :unique_filename           => Cloudinary::Utils.as_safe_bool(options[:unique_filename]),
       :upload_preset             => options[:upload_preset],
       :use_filename              => Cloudinary::Utils.as_safe_bool(options[:use_filename]),
+      :use_filename_as_display_name => Cloudinary::Utils.as_safe_bool(options[:use_filename_as_display_name]),
       :accessibility_analysis    => Cloudinary::Utils.as_safe_bool(options[:accessibility_analysis]),
       :metadata                  => Cloudinary::Utils.encode_context(options[:metadata])
     }
@@ -110,6 +114,9 @@ class Cloudinary::Uploader
     else
       filename = "cloudinaryfile"
     end
+
+    filename = options[:filename] if options[:filename]
+
     unique_upload_id = Cloudinary::Utils.random_public_id
     upload     = nil
     index      = 0
@@ -159,7 +166,9 @@ class Cloudinary::Uploader
         :from_public_id => from_public_id,
         :to_public_id   => to_public_id,
         :to_type        => options[:to_type],
-        :invalidate     => Cloudinary::Utils.as_safe_bool(options[:invalidate])
+        :invalidate     => Cloudinary::Utils.as_safe_bool(options[:invalidate]),
+        :context        => options[:context],
+        :metadata       => options[:metadata]
       }
     end
   end
@@ -207,17 +216,42 @@ class Cloudinary::Uploader
     end
   end
 
-  def self.generate_sprite(tag, options={})
+  SLIDESHOW_PARAMS = [:notification_url, :public_id, :upload_preset]
+
+  # Creates auto-generated video slideshow.
+  #
+  # @param [Hash] options Additional options.
+  #
+  # @return [Hash] Hash with meta information URLs of generated slideshow resources.
+  def self.create_slideshow(options = {})
+    options[:resource_type] ||= :video
+
+    call_api("create_slideshow", options) do
+      params = {
+        :timestamp               => Time.now.to_i,
+        :transformation          => Cloudinary::Utils.build_eager(options[:transformation]),
+        :manifest_transformation => Cloudinary::Utils.build_eager(options[:manifest_transformation]),
+        :manifest_json           => options[:manifest_json] && options[:manifest_json].to_json,
+        :tags                    => options[:tags] && Cloudinary::Utils.build_array(options[:tags]).join(","),
+        :overwrite               => Cloudinary::Utils.as_safe_bool(options[:overwrite])
+      }
+      SLIDESHOW_PARAMS.each { |k| params[k] = options[k] unless options[k].nil? }
+
+      params
+    end
+  end
+
+  # Generates sprites by merging multiple images into a single large image.
+  #
+  # @param [String|Hash] tag Treated as additional options when hash is passed, otherwise as a tag
+  # @param [Hash] options Additional options. Should be omitted when +tag_or_options+ is a Hash
+  #
+  # @return [Hash] Hash with meta information URLs of generated sprite resources
+  def self.generate_sprite(tag, options = {})
     version_store = options.delete(:version_store)
 
     result = call_api("sprite", options) do
-      {
-        :timestamp        => (options[:timestamp] || Time.now.to_i),
-        :tag              => tag,
-        :async            => options[:async],
-        :notification_url => options[:notification_url],
-        :transformation   => Cloudinary::Utils.generate_transformation_string(options.merge(:fetch_format => options[:format]))
-      }
+      Cloudinary::Utils.build_multi_and_sprite_params(tag, options)
     end
 
     if version_store == :file && result && result["version"]
@@ -229,16 +263,15 @@ class Cloudinary::Uploader
     return result
   end
 
-  def self.multi(tag, options={})
+  # Creates either a single animated image, video or a PDF.
+  #
+  # @param [String|Hash] tag Treated as additional options when hash is passed, otherwise as a tag
+  # @param [Hash] options Additional options. Should be omitted when +tag_or_options+ is a Hash
+  #
+  # @return [Hash] Hash with meta information URLs of the generated file
+  def self.multi(tag, options = {})
     call_api("multi", options) do
-      {
-        :timestamp        => (options[:timestamp] || Time.now.to_i),
-        :tag              => tag,
-        :format           => options[:format],
-        :async            => options[:async],
-        :notification_url => options[:notification_url],
-        :transformation   => Cloudinary::Utils.generate_transformation_string(options.clone)
-      }
+      Cloudinary::Utils.build_multi_and_sprite_params(tag, options)
     end
   end
 
@@ -337,11 +370,19 @@ class Cloudinary::Uploader
     options      = options.clone
     return_error = options.delete(:return_error)
     use_cache = options[:use_cache] || Cloudinary.config.use_cache
-
     params, non_signable = yield
     non_signable         ||= []
 
-    unless options[:unsigned]
+    headers                       = { "User-Agent" => Cloudinary::USER_AGENT }
+    headers['Content-Range']      = options[:content_range] if options[:content_range]
+    headers['X-Unique-Upload-Id'] = options[:unique_upload_id] if options[:unique_upload_id]
+    headers.merge!(options[:extra_headers]) if options[:extra_headers]
+
+    oauth_token = options[:oauth_token] || Cloudinary.config.oauth_token
+
+    if oauth_token
+      headers["Authorization"] = "Bearer #{oauth_token}"
+    elsif !options[:unsigned]
       api_key             = options[:api_key] || Cloudinary.config.api_key || raise(CloudinaryException, "Must supply api_key")
       api_secret          = options[:api_secret] || Cloudinary.config.api_secret || raise(CloudinaryException, "Must supply api_secret")
       signature_algorithm = options[:signature_algorithm]
@@ -353,11 +394,7 @@ class Cloudinary::Uploader
 
     result = nil
 
-    api_url                  = Cloudinary::Utils.cloudinary_api_url(action, options)
-    headers                  = { "User-Agent" => Cloudinary::USER_AGENT }
-    headers['Content-Range'] = options[:content_range] if options[:content_range]
-    headers['X-Unique-Upload-Id'] = options[:unique_upload_id] if options[:unique_upload_id]
-    headers.merge!(options[:extra_headers]) if options[:extra_headers]
+    api_url = Cloudinary::Utils.cloudinary_api_url(action, options)
     RestClient::Request.execute(:method => :post, :url => api_url, :payload => params.reject { |k, v| v.nil? || v=="" }, :timeout => timeout, :headers => headers, :proxy => proxy) do
     |response, request, tmpresult|
       raise CloudinaryException, "Server returned unexpected status code - #{response.code} - #{response.body}" unless [200, 400, 401, 403, 404, 500].include?(response.code)

data/lib/cloudinary/utils.rb

@@ -13,6 +13,7 @@ require 'cloudinary/responsive'
 class Cloudinary::Utils
   # @deprecated Use Cloudinary::SHARED_CDN
   SHARED_CDN = Cloudinary::SHARED_CDN
+  MODE_DOWNLOAD = "download"
   DEFAULT_RESPONSIVE_WIDTH_TRANSFORMATION = {:width => :auto, :crop => :limit}
   CONDITIONAL_OPERATORS = {
     "=" => 'eq',
@@ -334,7 +335,7 @@ class Cloudinary::Utils
     "if_" + normalize_expression(if_value) unless if_value.to_s.empty?
   end
 
-  EXP_REGEXP = Regexp.new('(\$_*[^_ ]+)|(?<!\$)('+PREDEFINED_VARS.keys.join("|")+')'+'|('+CONDITIONAL_OPERATORS.keys.reverse.map { |k| Regexp.escape(k) }.join('|')+')(?=[ _])')
+  EXP_REGEXP = Regexp.new('(\$_*[^_ ]+)|(?<![\$:])('+PREDEFINED_VARS.keys.join("|")+')'+'|('+CONDITIONAL_OPERATORS.keys.reverse.map { |k| Regexp.escape(k) }.join('|')+')(?=[ _])')
   EXP_REPLACEMENT = PREDEFINED_VARS.merge(CONDITIONAL_OPERATORS)
 
   def self.normalize_expression(expression)
@@ -351,18 +352,30 @@ class Cloudinary::Utils
   # @return [string] layer transformation string
   # @private
   def self.process_layer(layer)
+     if layer.is_a? String and layer.start_with?("fetch:")
+      layer = {:url => layer[6..-1]} # omit "fetch:" prefix
+     end
      if layer.is_a? Hash
        layer = symbolize_keys layer
        public_id     = layer[:public_id]
        format        = layer[:format]
+       fetch         = layer[:url]
        resource_type = layer[:resource_type] || "image"
-       type          = layer[:type] || "upload"
+       type          = layer[:type]
        text          = layer[:text]
        text_style    = nil
        components    = []
 
+       if type.nil?
+         if fetch.nil?
+           type = "upload"
+         else
+           type = "fetch"
+         end
+       end
+
        if public_id.present?
-          if type == "fetch" && public_id.match(%r(^https?:/)i)
+          if type == "fetch" and public_id.match(%r(^https?:/)i)
             public_id = Base64.urlsafe_encode64(public_id)
           else
             public_id = public_id.gsub("/", ":")
@@ -370,14 +383,15 @@ class Cloudinary::Utils
           end
        end
 
-       if text.blank? && resource_type != "text"
-         if public_id.blank?
+       if fetch.present? && fetch.match(%r(^https?:/)i)
+         fetch = Base64.urlsafe_encode64(fetch)
+       elsif text.blank? && resource_type != "text"
+         if public_id.blank? && type != "fetch"
            raise(CloudinaryException, "Must supply public_id for resource_type layer_parameter")
          end
          if resource_type == "subtitles"
            text_style = text_style(layer)
          end
-
        else
          resource_type = "text"
          type          = nil
@@ -403,6 +417,7 @@ class Cloudinary::Utils
        components.push(type) if type != "upload"
        components.push(text_style)
        components.push(public_id)
+       components.push(fetch)
        components.push(text)
        layer = components.reject(&:blank?).join(":")
      end
@@ -430,6 +445,8 @@ class Cloudinary::Utils
   ]
 
   def self.text_style(layer)
+    return layer[:text_style] if layer[:text_style].present?
+
     font_family = layer[:font_family]
     font_size   = layer[:font_size]
     keywords    = []
@@ -719,6 +736,43 @@ class Cloudinary::Utils
     params
   end
 
+  # Helper method for generating download URLs
+  #
+  # @param [String] action @see Cloudinary::Utils.cloudinary_api_url
+  # @param [Hash] params Query parameters in generated URL
+  # @param [Hash] options Additional options
+  # @yield [query_parameters] Invokes the block with query parameters to override how to encode them
+  #
+  # @return [String]
+  def self.cloudinary_api_download_url(action, params, options = {})
+    cloudinary_params = sign_request(params.merge(mode: MODE_DOWNLOAD), options)
+
+    "#{Cloudinary::Utils.cloudinary_api_url(action, options)}?#{hash_query_params(cloudinary_params)}"
+  end
+  private_class_method :cloudinary_api_download_url
+
+  # Return a signed URL to the 'generate_sprite' endpoint with 'mode=download'.
+  #
+  # @param [String|Hash] tag Treated as additional options when hash is passed, otherwise as a tag
+  # @param [Hash] options Additional options. Should be omitted when +tag_or_options+ is a Hash
+  #
+  # @return [String] The signed URL to download sprite
+  def self.download_generated_sprite(tag, options = {})
+    params = build_multi_and_sprite_params(tag, options)
+    cloudinary_api_download_url("sprite", params, options)
+  end
+
+  # Return a signed URL to the 'multi' endpoint with 'mode=download'.
+  #
+  # @param [String|Hash] tag Treated as additional options when hash is passed, otherwise as a tag
+  # @param [Hash] options Additional options. Should be omitted when +tag_or_options+ is a Hash
+  #
+  # @return [String] The signed URL to download multi
+  def self.download_multi(tag, options = {})
+    params = build_multi_and_sprite_params(tag, options)
+    cloudinary_api_download_url("multi", params, options)
+  end
+
   def self.private_download_url(public_id, format, options = {})
     cloudinary_params = sign_request({
         :timestamp=>Time.now.to_i,
@@ -767,11 +821,10 @@ class Cloudinary::Utils
   # @option options [String] :keep_derived (false) keep the derived images used for generating the archive
   # @return [String] archive url
   def self.download_archive_url(options = {})
-    cloudinary_params = sign_request(Cloudinary::Utils.archive_params(options.merge(:mode => "download")), options)
-    return Cloudinary::Utils.cloudinary_api_url("generate_archive", options) + "?" + hash_query_params(cloudinary_params)
+    params = Cloudinary::Utils.archive_params(options)
+    cloudinary_api_download_url("generate_archive", params, options)
   end
 
-
   # Returns a URL that when invokes creates an zip archive and returns it.
   # @see download_archive_url
   def self.download_zip_url(options = {})
@@ -832,7 +885,7 @@ class Cloudinary::Utils
 
   # Based on CGI::unescape. In addition keeps '+' character as is
   def self.smart_unescape(string)
-    CGI.unescape(string.sub('+', '%2B'))
+    CGI.unescape(string.gsub('+', '%2B'))
   end
 
   def self.random_public_id
@@ -1050,7 +1103,7 @@ class Cloudinary::Utils
     Cloudinary::AuthToken.generate options
 
   end
-  
+
   private
 
 
@@ -1067,24 +1120,24 @@ class Cloudinary::Utils
     source
   end
   private_class_method :fully_unescape
-  
+
   def self.hash_query_params(hash)
     if hash.respond_to?("to_query")
       hash.to_query
     else
-      flat_hash_to_query_params(hash)      
+      flat_hash_to_query_params(hash)
     end
   end
 
   def self.flat_hash_to_query_params(hash)
-    hash.collect do |key, value|      
+    hash.collect do |key, value|
       if value.is_a?(Array)
         value.map{|v| "#{CGI.escape(key.to_s)}[]=#{CGI.escape(v.to_s)}"}.join("&")
-      else  
+      else
         "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
-      end        
+      end
     end.compact.sort!.join('&')
-  end  
+  end
 
   def self.number_pattern
     "([0-9]*)\\.([0-9]+)|([0-9]+)"
@@ -1132,9 +1185,10 @@ class Cloudinary::Utils
 
   # A video codec parameter can be either a String or a Hash.
   #
-  # @param [Object] param <code>vc_<codec>[ : <profile> : [<level>]]</code>
+  # @param [Object] param <code>vc_<codec>[ : <profile> : [<level> : [<b_frames>]]]</code>
   #                       or <code>{ codec: 'h264', profile: 'basic', level: '3.1' }</code>
-  # @return [String] <code><codec> : <profile> : [<level>]]</code> if a Hash was provided
+  #                       or <code>{ codec: 'h265', profile: 'auto', level: 'auto', b_frames: false }</code>
+  # @return [String] <code><codec> : <profile> : [<level> : [<b_frames>]]]</code> if a Hash was provided
   #                   or the param if a String was provided.
   #                   Returns NIL if param is not a Hash or String
   # @private
@@ -1148,6 +1202,9 @@ class Cloudinary::Utils
           video.concat ":" + param[:profile]
           if param.has_key? :level
             video.concat ":" + param[:level]
+            if param.has_key?(:b_frames) && param[:b_frames] === false
+              video.concat ":bframes_no"
+            end
           end
         end
       end
@@ -1191,6 +1248,41 @@ class Cloudinary::Utils
     REMOTE_URL_REGEX === url
   end
 
+  # Build params for multi, download_multi, generate_sprite, and download_generated_sprite methods
+  #
+  # @param [String|Hash] tag_or_options Treated as additional options when hash is passed, otherwise as a tag
+  # @param [Hash] options Additional options. Should be omitted when +tag_or_options+ is a Hash
+  #
+  # @return [Hash]
+  #
+  # @private
+  def self.build_multi_and_sprite_params(tag_or_options, options)
+    if tag_or_options.is_a?(Hash)
+      if options.blank?
+        options = tag_or_options
+        tag_or_options = nil
+      else
+        raise "First argument must be a tag when additional options are passed"
+      end
+    end
+    urls = options.delete(:urls)
+
+    if tag_or_options.blank? && urls.blank?
+      raise "Either tag or urls are required"
+    end
+
+    {
+      :tag => tag_or_options,
+      :urls => urls,
+      :transformation => Cloudinary::Utils.generate_transformation_string(options.merge(:fetch_format => options[:format])),
+      :notification_url => options[:notification_url],
+      :format => options[:format],
+      :async => options[:async],
+      :mode => options[:mode],
+      :timestamp => (options[:timestamp] || Time.now.to_i)
+    }
+  end
+
   # The returned url should allow downloading the backedup asset based on the version and asset id
   #
   # asset and version id are returned with resource(<PUBLIC_ID1>, { versions: true })
@@ -1224,10 +1316,53 @@ class Cloudinary::Utils
     end
   end
 
+  # Verifies the authenticity of an API response signature.
+  #
+  # @param [String] public_id he public id of the asset as returned in the API response
+  # @param [Fixnum] version The version of the asset as returned in the API response
+  # @param [String] signature Actual signature. Can be retrieved from the X-Cld-Signature header
+  # @param [Symbol|nil] signature_algorithm Algorithm to use for computing hash
+  # @param [Hash] options
+  # @option options [String] :api_secret API secret, if not passed taken from global config
+  #
+  # @return [Boolean]
+  def self.verify_api_response_signature(public_id, version, signature, signature_algorithm = nil, options = {})
+    api_secret = options[:api_secret] || Cloudinary.config.api_secret || raise("Must supply api_secret")
+
+    parameters_to_sign = {
+      :public_id => public_id,
+      :version => version
+    }
+
+    signature == api_sign_request(parameters_to_sign, api_secret, signature_algorithm)
+  end
+
+  # Verifies the authenticity of a notification signature.
+  #
+  # @param [String] body JSON of the request's body
+  # @param [Fixnum] timestamp Unix timestamp. Can be retrieved from the X-Cld-Timestamp header
+  # @param [String] signature Actual signature. Can be retrieved from the X-Cld-Signature header
+  # @param [Fixnum] valid_for The desired time in seconds for considering the request valid
+  # @param [Symbol|nil] signature_algorithm Algorithm to use for computing hash
+  # @param [Hash] options
+  # @option options [String] :api_secret API secret, if not passed taken from global config
+  #
+  # @return [Boolean]
+  def self.verify_notification_signature(body, timestamp, signature, valid_for = 7200, signature_algorithm = nil, options = {})
+    api_secret = options[:api_secret] || Cloudinary.config.api_secret || raise("Must supply api_secret")
+    raise("Body should be of String type") unless body.is_a?(String)
+    # verify that signature is valid for the given timestamp
+    return false if timestamp < (Time.now - valid_for).to_i
+
+    payload_hash = hash("#{body}#{timestamp}#{api_secret}", signature_algorithm, :hexdigest)
+
+    signature == payload_hash
+  end
+
   # Computes hash from input string using specified algorithm.
   #
   # @param [String] input                   String which to compute hash from
-  # @param [String|nil] signature_algorithm Algorithm to use for computing hash
+  # @param [Symbol|nil] signature_algorithm Algorithm to use for computing hash
   # @param [Symbol] hash_method             Hash method applied to a signature algorithm (:digest or :hexdigest)
   #
   # @return [String] Computed hash value

data/lib/cloudinary/version.rb

@@ -1,4 +1,4 @@
 # Copyright Cloudinary
 module Cloudinary
-  VERSION = "1.20.0"
+  VERSION = "1.23.0"
 end