cloudinary 1.17.0 → 1.20.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={})
@@ -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={})
@@ -348,47 +340,156 @@ class Cloudinary::Api
     call_json_api('GET', json_url, {}, 60, {})
   end
 
+  # Returns a list of all metadata field definitions.
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_metadata_fields Get metadata fields API reference
+  #
+  # @param [Hash] options Additional options
+  # @return [Cloudinary::Api::Response]
+  # @raise [Cloudinary::Api::Error]
+  def self.list_metadata_fields(options = {})
+    call_metadata_api(:get, [], {}, options)
+  end
+
+  # Gets a metadata field by external id.
+  #
+  # @see https://cloudinary.com/documentation/admin_api#get_a_metadata_field_by_external_id Get metadata field by external ID API reference
+  #
+  # @param [String] field_external_id The ID of the metadata field to retrieve
+  # @param [Hash]   options           Additional options
+  # @return [Cloudinary::Api::Response]
+  # @raise [Cloudinary::Api::Error]
+  def self.metadata_field_by_field_id(field_external_id, options = {})
+    uri = [field_external_id]
+
+    call_metadata_api(:get, uri, {}, options)
+  end
+
+  # Creates a new metadata field definition.
+  #
+  # @see https://cloudinary.com/documentation/admin_api#create_a_metadata_field Create metadata field API reference
+  #
+  # @param [Hash] field   The field to add
+  # @param [Hash] options Additional options
+  # @return [Cloudinary::Api::Response]
+  # @raise [Cloudinary::Api::Error]
+  def self.add_metadata_field(field, options = {})
+    params = only(field, :type, :external_id, :label, :mandatory, :default_value, :validation, :datasource)
+
+    call_metadata_api(:post, [], params, options)
+  end
+
+  # Updates a metadata field by external id.
+  #
+  # Updates a metadata field definition (partially, no need to pass the entire object) passed as JSON data.
+  # See https://cloudinary.com/documentation/admin_api#generic_structure_of_a_metadata_field for the generic structure
+  # of a metadata field.
+  #
+  # @see https://cloudinary.com/documentation/admin_api#update_a_metadata_field_by_external_id Update metadata field API reference
+  #
+  # @param [String] field_external_id The id of the metadata field to update
+  # @param [Hash]   field             The field definition
+  # @param [Hash]   options           Additional options
+  # @return [Cloudinary::Api::Response]
+  # @raise [Cloudinary::Api::Error]
+  def self.update_metadata_field(field_external_id, field, options = {})
+    uri = [field_external_id]
+    params = only(field, :label, :mandatory, :default_value, :validation)
+
+    call_metadata_api(:put, uri, params, options)
+  end
+
+  # Deletes a metadata field definition.
+  #
+  # The field should no longer be considered a valid candidate for all other endpoints.
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_a_metadata_field_by_external_id Delete metadata field API reference
+  #
+  # @param [String] field_external_id The external id of the field to delete
+  # @param [Hash]   options           Additional options
+  # @return [Cloudinary::Api::Response] A hash with a "message" key. "ok" value indicates a successful deletion
+  # @raise [Cloudinary::Api::Error]
+  def self.delete_metadata_field(field_external_id, options = {})
+    uri = [field_external_id]
+
+    call_metadata_api(:delete, uri, {}, options)
+  end
+
+  # Deletes entries in a metadata field datasource.
+  #
+  # Deletes (blocks) the datasource entries for a specified metadata field definition. Sets the state of the
+  # entries to inactive. This is a soft delete, the entries still exist under the hood and can be activated
+  # again with the restore datasource entries method.
+  #
+  # @see https://cloudinary.com/documentation/admin_api#delete_entries_in_a_metadata_field_datasource Delete entries in a metadata field datasource API reference
+  #
+  # @param [String] field_external_id    The id of the field to update
+  # @param [Array]  entries_external_id  The ids of all the entries to delete from the datasource
+  # @param [Hash]   options              Additional options
+  # @return [Cloudinary::Api::Response] The remaining datasource entries
+  # @raise [Cloudinary::Api::Error]
+  def self.delete_datasource_entries(field_external_id, entries_external_id, options = {})
+    uri = [field_external_id, "datasource"]
+    params = {:external_ids => entries_external_id }
+
+    call_metadata_api(:delete, uri, params, options)
+  end
+
+  # Updates a metadata field datasource.
+  #
+  # Updates the datasource of a supported field type (currently only enum and set), passed as JSON data. The
+  # update is partial: datasource entries with an existing external_id will be updated and entries with new
+  # external_id’s (or without external_id’s) will be appended.
+  #
+  # @see https://cloudinary.com/documentation/admin_api#update_a_metadata_field_datasource Update a metadata field datasource API reference
+  #
+  # @param [String] field_external_id   The external id of the field to update
+  # @param [Array]  entries_external_id
+  # @param [Hash]   options             Additional options
+  # @return [Cloudinary::Api::Response]
+  # @raise [Cloudinary::Api::Error]
+  def self.update_metadata_field_datasource(field_external_id, entries_external_id, options = {})
+    uri = [field_external_id, "datasource"]
+
+    params = entries_external_id.each_with_object({:values => [] }) do |item, hash|
+      item = only(item, :external_id, :value)
+      hash[:values ] << item if item.present?
+    end
+
+    call_metadata_api(:put, uri, params, options)
+  end
+
+  # Restores entries in a metadata field datasource.
+  #
+  # Restores (unblocks) any previously deleted datasource entries for a specified metadata field definition.
+  # Sets the state of the entries to active.
+  #
+  # @see https://cloudinary.com/documentation/admin_api#restore_entries_in_a_metadata_field_datasource Restore entries in a metadata field datasource API reference
+  #
+  # @param [String] field_external_id    The ID of the metadata field
+  # @param [Array]  entries_external_ids An array of IDs of datasource entries to restore (unblock)
+  # @param [Hash]   options              Additional options
+  # @return [Cloudinary::Api::Response]
+  # @raise [Cloudinary::Api::Error]
+  def self.restore_metadata_field_datasource(field_external_id, entries_external_ids, options = {})
+    uri = [field_external_id, "datasource_restore"]
+    params = {:external_ids => entries_external_ids }
+
+    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
@@ -396,6 +497,22 @@ class Cloudinary::Api
     raise GeneralError.new("Error parsing server response (#{response.code}) - #{response.body}. Got - #{e}")
   end
 
+  # Protected function that assists with performing an API call to the metadata_fields 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_fields')
+  # @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]
+  # @raise [Cloudinary::Api::Error]
+  def self.call_metadata_api(method, uri, params, options)
+    options[:content_type] = :json
+    uri = ["metadata_fields", uri].reject(&:empty?).join("/")
+
+    call_api(method, uri, params, options)
+  end
+
   def self.only(hash, *keys)
     result = {}
     keys.each do |key|
@@ -439,5 +556,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