cloudinary 1.18.0 → 1.21.0

data/lib/cloudinary/account_config.rb

@@ -0,0 +1,30 @@
+module Cloudinary
+  module AccountConfig
+    include BaseConfig
+
+    ENV_URL = "CLOUDINARY_ACCOUNT_URL"
+    SCHEME = "account"
+
+    def load_config_from_env
+      load_from_url(ENV[ENV_URL]) if ENV[ENV_URL]
+    end
+
+    private
+
+    def env_url
+      ENV_URL
+    end
+
+    def expected_scheme
+      SCHEME
+    end
+
+    def config_from_parsed_url(parsed_url)
+      {
+        "account_id"              => parsed_url.host,
+        "provisioning_api_key"    => parsed_url.user,
+        "provisioning_api_secret" => parsed_url.password
+      }
+    end
+  end
+end

data/lib/cloudinary/api.rb

@@ -1,37 +1,28 @@
-require 'rest_client'
-require 'json'
-
 class Cloudinary::Api
-  class Error < CloudinaryException; end
-  class NotFound < Error; end
-  class NotAllowed < Error; end
-  class AlreadyExists < Error; end
-  class RateLimited < Error; end
-  class BadRequest < Error; end
-  class GeneralError < Error; end
-  class AuthorizationRequired < Error; end
-
-  class Response < Hash
-    attr_reader :rate_limit_reset_at, :rate_limit_remaining, :rate_limit_allowed
-
-    def initialize(response=nil)
-      if response
-        # 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]
-      end
-    end
-  end
+  extend Cloudinary::BaseApi
 
   def self.ping(options={})
     call_api(:get, "ping", {}, options)
   end
 
+  # Gets account usage details
+  #
+  # Get a report on the status of your Cloudinary account usage details, including
+  # storage, bandwidth, requests, number of resources, and add-on usage.
+  # Note that numbers are updated periodically.
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_account_usage_details Get account usage details
+  #
+  # @param [Hash] options Additional options
+  # @return [Cloudinary::Api::Response]
+  # @raise [Cloudinary::Api:Error]
   def self.usage(options={})
-    call_api(:get, "usage", {}, options)
+    uri = 'usage'
+    date = options[:date]
+
+    uri += "/#{Cloudinary::Utils.to_usage_api_date_format(date)}" unless date.nil?
+
+    call_api(:get, uri, {}, options)
   end
 
   def self.resource_types(options={})
@@ -43,25 +34,25 @@ class Cloudinary::Api
     type          = options[:type]
     uri           = "resources/#{resource_type}"
     uri           += "/#{type}" unless type.blank?
-    call_api(:get, uri, only(options, :next_cursor, :max_results, :prefix, :tags, :context, :moderations, :direction, :start_at), options)
+    call_api(:get, uri, only(options, :next_cursor, :max_results, :prefix, :tags, :context, :moderations, :direction, :start_at, :metadata), options)
   end
 
   def self.resources_by_tag(tag, options={})
     resource_type = options[:resource_type] || "image"
     uri           = "resources/#{resource_type}/tags/#{tag}"
-    call_api(:get, uri, only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction), options)
+    call_api(:get, uri, only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction, :metadata), options)
   end
 
   def self.resources_by_moderation(kind, status, options={})
     resource_type = options[:resource_type] || "image"
     uri           = "resources/#{resource_type}/moderations/#{kind}/#{status}"
-    call_api(:get, uri, only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction), options)
+    call_api(:get, uri, only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction, :metadata), options)
   end
 
   def self.resources_by_context(key, value=nil, options={})
     resource_type = options[:resource_type] || "image"
     uri           = "resources/#{resource_type}/context"
-    params = only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction,:key,:value)
+    params = only(options, :next_cursor, :max_results, :tags, :context, :moderations, :direction, :key, :value, :metadata)
     params[:key] = key
     params[:value] = value
     call_api(:get, uri, params, options)
@@ -91,7 +82,8 @@ class Cloudinary::Api
                   :phash,
                   :quality_analysis,
                   :derived_next_cursor,
-                  :accessibility_analysis
+                  :accessibility_analysis,
+                  :versions
              ), options)
   end
 
@@ -99,7 +91,7 @@ class Cloudinary::Api
     resource_type = options[:resource_type] || "image"
     type          = options[:type] || "upload"
     uri           = "resources/#{resource_type}/#{type}/restore"
-    call_api(:post, uri, { :public_ids => public_ids }, options)
+    call_api(:post, uri, { :public_ids => public_ids, :versions => options[:versions] }, options)
   end
 
   def self.update(public_id, options={})
@@ -185,24 +177,32 @@ class Cloudinary::Api
   end
 
   def self.transformation(transformation, options={})
-    call_api(:get, "transformations/#{transformation_string(transformation)}", only(options, :next_cursor, :max_results), options)
+    params                  = only(options, :next_cursor, :max_results)
+    params[:transformation] = Cloudinary::Utils.build_eager(transformation)
+    call_api(:get, "transformations", params, options)
   end
 
   def self.delete_transformation(transformation, options={})
-    call_api(:delete, "transformations/#{transformation_string(transformation)}", {}, options)
+    call_api(:delete, "transformations", {:transformation => Cloudinary::Utils.build_eager(transformation)}, options)
   end
 
   # updates - supports:
   #   "allowed_for_strict" boolean
   #   "unsafe_update" transformation params - updates a named transformation parameters without regenerating existing images
   def self.update_transformation(transformation, updates, options={})
-    params                 = only(updates, :allowed_for_strict)
-    params[:unsafe_update] = transformation_string(updates[:unsafe_update]) if updates[:unsafe_update]
-    call_api(:put, "transformations/#{transformation_string(transformation)}", params, options)
+    params                  = only(updates, :allowed_for_strict)
+    params[:unsafe_update]  = Cloudinary::Utils.build_eager(updates[:unsafe_update]) if updates[:unsafe_update]
+    params[:transformation] = Cloudinary::Utils.build_eager(transformation)
+    call_api(:put, "transformations", params, options)
   end
 
   def self.create_transformation(name, definition, options={})
-    call_api(:post, "transformations/#{name}", { :transformation => transformation_string(definition) }, options)
+    params = {
+      :name => name,
+      :transformation => Cloudinary::Utils.build_eager(definition)
+    }
+
+    call_api(:post, "transformations", params, options)
   end
 
   # upload presets
@@ -220,12 +220,12 @@ class Cloudinary::Api
 
   def self.update_upload_preset(name, options={})
     params = Cloudinary::Uploader.build_upload_params(options)
-    call_api(:put, "upload_presets/#{name}", params.merge(only(options, :unsigned, :disallow_public_id)), options)
+    call_api(:put, "upload_presets/#{name}", params.merge(only(options, :unsigned, :disallow_public_id, :live)), options)
   end
 
   def self.create_upload_preset(options={})
     params = Cloudinary::Uploader.build_upload_params(options)
-    call_api(:post, "upload_presets", params.merge(only(options, :name, :unsigned, :disallow_public_id)), options)
+    call_api(:post, "upload_presets", params.merge(only(options, :name, :unsigned, :disallow_public_id, :live)), options)
   end
 
   def self.root_folders(options={})
@@ -486,47 +486,35 @@ class Cloudinary::Api
     call_metadata_api(:post, uri, params, options)
   end
 
+  # Reorders metadata field datasource. Currently supports only value.
+  #
+  # @param [String] field_external_id The ID of the metadata field
+  # @param [String] order_by          Criteria for the order. Currently supports only value
+  # @param [String] direction         Optional (gets either asc or desc)
+  # @param [Hash]   options           Configuration options
+  #
+  # @return [Cloudinary::Api::Response]
+  #
+  # @raise [Cloudinary::Api::Error]
+  def self.reorder_metadata_field_datasource(field_external_id, order_by, direction = nil, options = {})
+    uri    = [field_external_id, "datasource", "order"]
+    params = { :order_by => order_by, :direction => direction }
+
+    call_metadata_api(:post, uri, params, options)
+  end
+
   protected
 
   def self.call_api(method, uri, params, options)
-    cloudinary = options[:upload_prefix] || Cloudinary.config.upload_prefix || "https://api.cloudinary.com"
-    cloud_name = options[:cloud_name] || Cloudinary.config.cloud_name || raise("Must supply cloud_name")
-    api_key    = options[:api_key] || Cloudinary.config.api_key || raise("Must supply api_key")
-    api_secret = options[:api_secret] || Cloudinary.config.api_secret || raise("Must supply api_secret")
-    timeout    = options[:timeout] || Cloudinary.config.timeout || 60
-    uri = Cloudinary::Utils.smart_escape(uri)
-    api_url    = [cloudinary, "v1_1", cloud_name, uri].join("/")
-    # Add authentication
-    api_url.sub!(%r(^(https?://)), "\\1#{api_key}:#{api_secret}@")
-
-    headers = { "User-Agent" => Cloudinary::USER_AGENT }
-    if options[:content_type]== :json
-      payload = params.to_json
-      headers.merge!("Content-Type"=> 'application/json', "Accept"=> 'application/json')
-    else
-      payload = params.reject { |k, v| v.nil? || v=="" }
-    end
-    call_json_api(method, api_url, payload, timeout, headers)
-  end
-
-  def self.call_json_api(method, api_url, payload, timeout, headers)
-    RestClient::Request.execute(:method => method, :url => api_url, :payload => payload, :timeout => timeout, :headers => headers) do
-    |response, request, tmpresult|
-      return Response.new(response) if response.code == 200
-      exception_class = case response.code
-                        when 400 then BadRequest
-                        when 401 then AuthorizationRequired
-                        when 403 then NotAllowed
-                        when 404 then NotFound
-                        when 409 then AlreadyExists
-                        when 420 then RateLimited
-                        when 500 then GeneralError
-                        else raise GeneralError.new("Server returned unexpected status code - #{response.code} - #{response.body}")
-                        end
-      json = parse_json_response(response)
-      raise exception_class.new(json["error"]["message"])
+    cloud_name = options[:cloud_name] || Cloudinary.config.cloud_name || raise('Must supply cloud_name')
+    api_key    = options[:api_key] || Cloudinary.config.api_key || raise('Must supply api_key')
+    api_secret = options[:api_secret] || Cloudinary.config.api_secret || raise('Must supply api_secret')
+
+    call_cloudinary_api(method, uri, api_key, api_secret, params, options) do |cloudinary, inner_uri|
+      [cloudinary, 'v1_1', cloud_name, inner_uri]
     end
   end
+
   def self.parse_json_response(response)
     return Cloudinary::Utils.json_decode(response.body)
   rescue => e
@@ -593,5 +581,4 @@ class Cloudinary::Api
     params[by_key] = value
     call_api("post", "resources/#{resource_type}/#{type}/update_access_mode", params, options)
   end
-
 end

data/lib/cloudinary/auth_token.rb

@@ -33,6 +33,10 @@ module Cloudinary
         end
       end
 
+      if url.blank? && acl.blank?
+        raise 'AuthToken must contain either an acl or a url property'
+      end
+
       token = []
       token << "ip=#{ip}" if ip
       token << "st=#{start}" if start

data/lib/cloudinary/base_api.rb

@@ -0,0 +1,79 @@
+require "rest_client"
+require "json"
+
+module Cloudinary::BaseApi
+  class Error < CloudinaryException; end
+  class NotFound < Error; end
+  class NotAllowed < Error; end
+  class AlreadyExists < Error; end
+  class RateLimited < Error; end
+  class BadRequest < Error; end
+  class GeneralError < Error; end
+  class AuthorizationRequired < Error; end
+
+  class Response < Hash
+    attr_reader :rate_limit_reset_at, :rate_limit_remaining, :rate_limit_allowed
+
+    def initialize(response=nil)
+      if response
+        # 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]
+      end
+    end
+  end
+
+  def self.extended(base)
+    [Error, NotFound, NotAllowed, AlreadyExists, RateLimited, BadRequest, GeneralError, AuthorizationRequired, Response].each do |constant|
+      base.const_set(constant.name.split("::").last, constant)
+    end
+  end
+
+  def call_json_api(method, api_url, payload, timeout, headers, proxy = nil, user = nil, password = nil)
+    RestClient::Request.execute(method: method,
+                                url: api_url,
+                                payload: payload,
+                                timeout: timeout,
+                                headers: headers,
+                                proxy: proxy,
+                                user: user,
+                                password: password) do |response|
+      return Response.new(response) if response.code == 200
+      exception_class = case response.code
+                        when 400 then BadRequest
+                        when 401 then AuthorizationRequired
+                        when 403 then NotAllowed
+                        when 404 then NotFound
+                        when 409 then AlreadyExists
+                        when 420 then RateLimited
+                        when 500 then GeneralError
+                        else raise GeneralError.new("Server returned unexpected status code - #{response.code} - #{response.body}")
+                        end
+      json = Cloudinary::Api.parse_json_response(response)
+      raise exception_class.new(json["error"]["message"])
+    end
+  end
+
+  private
+
+  def call_cloudinary_api(method, uri, user, password, 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 }
+
+    if options[:content_type] == :json
+      payload = params.to_json
+      headers.merge!("Content-Type" => "application/json", "Accept" => "application/json")
+    else
+      payload = params.reject { |_, v| v.nil? || v == "" }
+    end
+
+    call_json_api(method, api_url, payload, timeout, headers, proxy, user, password)
+  end
+end

data/lib/cloudinary/base_config.rb

@@ -0,0 +1,70 @@
+module Cloudinary
+  module BaseConfig
+    def load_from_url(url)
+      return unless url && !url.empty?
+
+      parsed_url = URI.parse(url)
+      scheme = parsed_url.scheme.to_s.downcase
+
+      if expected_scheme != scheme
+        raise(CloudinaryException,
+              "Invalid #{env_url} scheme. Expecting to start with '#{expected_scheme}://'")
+      end
+
+      update(config_from_parsed_url(parsed_url))
+      setup_from_parsed_url(parsed_url)
+    end
+
+    def update(new_config = {})
+      new_config.each{ |k,v| public_send(:"#{k}=", v) unless v.nil?}
+    end
+
+    def load_config_from_env
+      raise NotImplementedError
+    end
+
+    private
+
+    def config_from_parsed_url(parsed_url)
+      raise NotImplementedError
+    end
+
+    def env_url
+      raise NotImplementedError
+    end
+
+    def expected_scheme
+      raise NotImplementedError
+    end
+
+    def put_nested_key(key, value)
+      chain   = key.split(/[\[\]]+/).reject(&:empty?)
+      outer   = self
+      lastKey = chain.pop
+      chain.each do |innerKey|
+        inner = outer[innerKey]
+        if inner.nil?
+          inner           = OpenStruct.new
+          outer[innerKey] = inner
+        end
+        outer = inner
+      end
+      outer[lastKey] = value
+    end
+
+    def is_nested_key?(key)
+      /\w+\[\w+\]/ =~ key
+    end
+
+    def setup_from_parsed_url(parsed_url)
+      parsed_url.query.to_s.split("&").each do |param|
+        key, value = param.split("=")
+        if is_nested_key? key
+          put_nested_key key, value
+        else
+          update(key => Utils.smart_unescape(value))
+        end
+      end
+    end
+  end
+end

data/lib/cloudinary/config.rb

@@ -0,0 +1,43 @@
+module Cloudinary
+  module Config
+    include BaseConfig
+
+    ENV_URL = "CLOUDINARY_URL"
+    SCHEME = "cloudinary"
+
+    def load_config_from_env
+      if ENV["CLOUDINARY_CLOUD_NAME"]
+        config_keys = ENV.keys.select! { |key| key.start_with? "CLOUDINARY_" }
+        config_keys -= ["CLOUDINARY_URL"] # ignore it when explicit options are passed
+        config_keys.each do |full_key|
+          conf_key = full_key["CLOUDINARY_".length..-1].downcase # convert "CLOUDINARY_CONFIG_NAME" to "config_name"
+          conf_val = ENV[full_key]
+          conf_val = conf_val == 'true' if %w[true false].include?(conf_val) # cast relevant boolean values
+          update(conf_key => conf_val)
+        end
+      elsif ENV[ENV_URL]
+        load_from_url(ENV[ENV_URL])
+      end
+    end
+
+    private
+
+    def env_url
+      ENV_URL
+    end
+
+    def expected_scheme
+      SCHEME
+    end
+
+    def config_from_parsed_url(parsed_url)
+      {
+        "cloud_name"          => parsed_url.host,
+        "api_key"             => parsed_url.user,
+        "api_secret"          => parsed_url.password,
+        "private_cdn"         => !parsed_url.path.blank?,
+        "secure_distribution" => parsed_url.path[1..-1]
+      }
+    end
+  end
+end