uploadcare-ruby 2.1.2 → 3.1.0

data/lib/uploadcare/client/uploader_client.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative 'upload_client'
+require 'retries'
+require 'param/upload/upload_params_generator'
+
+module Uploadcare
+  module Client
+    # This is client for general uploads
+    #
+    # @see https://uploadcare.com/api-refs/upload-api/#tag/Upload
+    class UploaderClient < UploadClient
+      # @see https://uploadcare.com/api-refs/upload-api/#operation/baseUpload
+
+      def upload_many(arr, **options)
+        body = upload_many_body(arr, **options)
+        post(path: 'base/',
+             headers: { 'Content-Type': body.content_type },
+             body: body)
+      end
+
+      # syntactic sugar for upload_many
+      # There is actual upload method for one file, but it is redundant
+
+      def upload(file, **options)
+        upload_many([file], **options)
+      end
+
+      # Upload files from url
+      # @see https://uploadcare.com/api-refs/upload-api/#operation/fromURLUpload
+      # options:
+      # - check_URL_duplicates
+      # - filename
+      # - save_URL_duplicates
+      # - async - returns upload token instead of upload data
+      def upload_from_url(url, **options)
+        body = upload_from_url_body(url, **options)
+        token_response = post(path: 'from_url/', headers: { 'Content-Type': body.content_type }, body: body)
+        return token_response if options[:async]
+
+        uploaded_response = poll_upload_response(token_response.success[:token])
+        return uploaded_response if uploaded_response.success[:status] == 'error'
+
+        Dry::Monads::Success(files: [uploaded_response.success])
+      end
+
+      # Check upload status
+      #
+      # @see https://uploadcare.com/api-refs/upload-api/#operation/fromURLUploadStatus
+      def get_upload_from_url_status(token)
+        query_params = { token: token }
+        get(path: 'from_url/status/', params: query_params)
+      end
+
+      private
+
+      alias api_struct_post post
+      def post(**args)
+        handle_throttling { api_struct_post(**args) }
+      end
+
+      def poll_upload_response(token)
+        with_retries(max_tries: Uploadcare.config.max_request_tries,
+                     base_sleep_seconds: Uploadcare.config.base_request_sleep,
+                     max_sleep_seconds: Uploadcare.config.max_request_sleep) do
+          response = get_upload_from_url_status(token)
+          raise RequestError if %w[progress waiting unknown].include?(response.success[:status])
+
+          response
+        end
+      end
+
+      # Prepares body for upload_many method
+      def upload_many_body(arr, **options)
+        files_formdata = arr.map do |file|
+          [HTTP::FormData::File.new(file).filename,
+           form_data_for(file)]
+        end.to_h
+        HTTP::FormData::Multipart.new(
+          Param::Upload::UploadParamsGenerator.call(options[:store]).merge(files_formdata)
+        )
+      end
+
+      STORE_VALUES_MAP = {
+        true => '1',
+        false => '0'
+      }.freeze
+
+      # Prepare upload_from_url initial request body
+      def upload_from_url_body(url, **options)
+        HTTP::FormData::Multipart.new(
+          options.merge(
+            'pub_key' => Uploadcare.config.public_key,
+            'source_url' => url,
+            'store' => STORE_VALUES_MAP[options[:store]]
+          )
+        )
+      end
+    end
+  end
+end

data/lib/uploadcare/client/webhook_client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative 'rest_client'
+
+module Uploadcare
+  module Client
+    # client for webhook management
+    # @see https://uploadcare.com/api-refs/rest-api/v0.5.0/#tag/Webhook
+    class WebhookClient < RestClient
+      # Create webhook
+      # @see https://uploadcare.com/docs/api_reference/rest/webhooks/#subscribe
+      def create(options = {})
+        body = {
+          'target_url': options[:target_url],
+          'event': options[:event] || 'file.uploaded',
+          'is_active': options[:is_active].nil? ? true : options[:is_active]
+        }.to_json
+        post(uri: '/webhooks/', content: body)
+      end
+
+      # Returns array (not paginated list) of webhooks
+      # @see https://uploadcare.com/docs/api_reference/rest/webhooks/#get-list
+      def list
+        get(uri: '/webhooks/')
+      end
+
+      # Permanently deletes subscription
+      # @see https://uploadcare.com/docs/api_reference/rest/webhooks/#unsubscribe
+      def delete(target_url)
+        body = { 'target_url': target_url }.to_json
+        post(uri: '/webhooks/unsubscribe/', content: body)
+      end
+
+      # Updates webhook
+      # @see https://uploadcare.com/docs/api_reference/rest/webhooks/#subscribe-update
+      def update(id, options = {})
+        body = options.to_json
+        post(uri: "/webhooks/#{id}/", content: body)
+      end
+
+      alias create_webhook create
+      alias list_webhooks list
+      alias delete_webhook delete
+      alias update_webhook update
+    end
+  end
+end

data/lib/uploadcare/concern/error_handler.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module Concerns
+    # Wrapper for responses
+    # raises errors instead of returning monads
+    module ErrorHandler
+      include Exception
+
+      # Extension of ApiStruct's failure method
+      #
+      # Raises errors instead of returning falsey objects
+      # @see https://github.com/rubygarage/api_struct/blob/master/lib/api_struct/client.rb#L55
+      def failure(response)
+        catch_upload_errors(response)
+        parsed_response = JSON.parse(response.body.to_s)
+        raise RequestError, parsed_response['detail'] || parsed_response.map { |k, v| "#{k}: #{v}" }.join('; ')
+      rescue JSON::ParserError
+        raise RequestError, response.body.to_s
+      end
+
+      # Extension of ApiStruct's wrap method
+      #
+      # Catches throttling errors and Upload API errors
+      #
+      # @see https://github.com/rubygarage/api_struct/blob/master/lib/api_struct/client.rb#L45
+      def wrap(response)
+        raise_throttling_error(response) if response.status == 429
+        return failure(response) if response.status >= 300
+
+        catch_upload_errors(response)
+        success(response)
+      end
+
+      private
+
+      # Raise ThrottleError. Also, tells in error when server will be ready for next request
+      def raise_throttling_error(response)
+        retry_after = response.headers['Retry-After'].to_i + 1 || 11
+        raise ThrottleError.new(retry_after), "Response throttled, retry #{retry_after} seconds later"
+      end
+
+      # Upload API returns its errors with code 200, and stores its actual code and details within response message
+      # This methods detects that and raises apropriate error
+      def catch_upload_errors(response)
+        return unless response.code == 200
+
+        parsed_response = JSON.parse(response.body.to_s)
+        error = parsed_response['error'] if parsed_response.is_a?(Hash)
+        raise RequestError, error if error
+      end
+    end
+  end
+end

data/lib/uploadcare/concern/throttle_handler.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module Concerns
+    # This module lets clients send request multiple times if request is throttled
+    module ThrottleHandler
+      # call given block. If ThrottleError is returned, it will wait and attempt again 4 more times
+      # @yield executable block (HTTP request that may be throttled)
+      def handle_throttling
+        (Uploadcare.config.max_throttle_attempts - 1).times do
+          # rubocop:disable Style/RedundantBegin
+          begin
+            return yield
+          rescue(Exception::ThrottleError) => e
+            wait_time = e.timeout
+            sleep(wait_time)
+            next
+          end
+          # rubocop:enable Style/RedundantBegin
+        end
+        yield
+      end
+    end
+  end
+end

data/lib/uploadcare/concern/upload_error_handler.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module Concerns
+    # Wrapper for responses
+    # raises errors instead of returning monads
+    module UploadErrorHandler
+      include Exception
+
+      # Extension of ApiStruct's failure method
+      #
+      # Raises errors instead of returning falsey objects
+      # @see https://github.com/rubygarage/api_struct/blob/master/lib/api_struct/client.rb#L55
+      def failure(response)
+        catch_throttling_error(response)
+        parsed_response = JSON.parse(response.body.to_s)
+        raise RequestError, parsed_response['detail']
+      rescue JSON::ParserError
+        raise RequestError, response.status
+      end
+
+      private
+
+      def catch_throttling_error(response)
+        return unless response.code == 429
+
+        retry_after = response.headers['Retry-After'].to_i + 1 || 11
+        raise ThrottleError.new(retry_after), "Response throttled, retry #{retry_after} seconds later"
+      end
+    end
+  end
+end

data/lib/uploadcare/entity/conversion/base_converter.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module Entity
+    module Conversion
+      # This serializer lets a user convert uploaded documents
+      # @see https://uploadcare.com/api-refs/rest-api/v0.6.0/#operation/documentConvert
+      class BaseConverter < Entity
+        class << self
+          # Converts files
+          #
+          # @param doc_params [Array] of hashes with params or [Hash]
+          # @option options [Boolean] :store (false) whether to store file on servers.
+          def convert(params, options = {})
+            files_params = params.is_a?(Hash) ? [params] : params
+            conversion_client.new.convert_many(files_params, options)
+          end
+
+          # Returns a status of a conversion job
+          #
+          # @param token [Integer, String] token obtained from a server in convert method
+          def status(token)
+            conversion_client.new.get_conversion_status(token)
+          end
+
+          private
+
+          def conversion_client
+            clients[:base]
+          end
+        end
+      end
+    end
+  end
+  include Conversion
+end

data/lib/uploadcare/entity/conversion/document_converter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'base_converter'
+
+module Uploadcare
+  module Entity
+    module Conversion
+      # This serializer lets a user convert uploaded documents
+      # @see https://uploadcare.com/api-refs/rest-api/v0.5.0/#operation/documentConvert
+      class DocumentConverter < BaseConverter
+        client_service Client::Conversion::DocumentConversionClient
+      end
+    end
+  end
+end

data/lib/uploadcare/entity/conversion/video_converter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'base_converter'
+
+module Uploadcare
+  module Entity
+    module Conversion
+      # This serializer lets a user convert uploaded videos, and usually returns an array of results
+      # @see https://uploadcare.com/api-refs/rest-api/v0.5.0/#operation/videoConvert
+      class VideoConverter < BaseConverter
+        client_service Client::Conversion::VideoConversionClient
+      end
+    end
+  end
+end

data/lib/uploadcare/entity/decorator/paginator.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module Entity
+    # @abstract
+    module Decorator
+      # provides pagination methods for things in Uploadcare that paginate,
+      # namely [FileList] and [Group]
+      #
+      # Requirements:
+      # - Should be Entity with Client
+      # - Associated Client should have `list` method that returns objects with pagination
+      # - Response should have :next, :previous, :total, :per_page params and :results fields
+      module Paginator
+        @entity ||= Hashie::Mash.new
+
+        # meta data of a pagination object
+        def meta
+          Hashie::Mash.new(next: @entity[:next], previous: @entity[:previous],
+                           total: @entity[:total], per_page: @entity[:per_page])
+        end
+
+        # Returns new instance of current object on next page
+        def next_page
+          url = @entity[:next]
+          return unless url
+
+          query = URI.decode_www_form(URI(url).query).to_h
+          query = query.map { |k, v| [k.to_sym, v] }.to_h
+          self.class.list(**query)
+        end
+
+        # Returns new instance of current object on previous page
+        def previous_page
+          url = @entity[:previous]
+          return unless url
+
+          query = URI.decode_www_form(URI(url).query).to_h
+          query = query.map { |k, v| [k.to_sym, v] }.to_h
+          self.class.list(**query)
+        end
+
+        # Attempts to load the entire list after offset into results of current object
+        #
+        # It's possible to avoid loading objects on previous pages by offsetting them first
+        def load
+          return if @entity[:next].nil? || @entity[:results].length == @entity[:total]
+
+          np = self
+          until np.next.nil?
+            np = np.next_page
+            @entity[:results].concat(np.results.map(&:to_h))
+          end
+          @entity[:next] = nil
+          @entity[:per_page] = @entity[:total]
+          self
+        end
+
+        # iterate through pages, starting with current one
+        #
+        # @yield [Block]
+        def each(&block)
+          current_page = self
+          while current_page
+            current_page.results.each(&block)
+            current_page = current_page.next_page
+          end
+        end
+
+        # Load and return all objects in list
+        #
+        # @return [Array]
+        def all
+          load[:results]
+        end
+      end
+    end
+  end
+end

data/lib/uploadcare/entity/entity.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+Gem.find_files('client/**/*.rb').each { |path| require path }
+
+module Uploadcare
+  # Entities represent objects existing in Uploadcare cloud
+  #
+  # Typically, Entities inherit class methods from {Client} instance methods
+  # @see Client
+  module Entity
+    # @abstract
+    class Entity < ApiStruct::Entity
+      include Client
+    end
+  end
+
+  include Entity
+end

data/lib/uploadcare/entity/file.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module Entity
+    # This serializer returns a single file
+    #
+    # @see https://uploadcare.com/docs/api_reference/rest/handling_projects/
+    class File < Entity
+      client_service FileClient
+
+      attr_entity :datetime_removed, :datetime_stored, :datetime_uploaded, :image_info, :is_image, :is_ready,
+                  :mime_type, :original_file_url, :original_filename, :size, :url, :uuid, :variations, :video_info,
+                  :source, :rekognition_info
+
+      # gets file's uuid - even if it's only initialized with url
+      # @returns [String]
+      def uuid
+        return @entity.uuid if @entity.uuid
+
+        uuid = @entity.url.gsub('https://ucarecdn.com/', '')
+        uuid.gsub(%r{/.*}, '')
+      end
+
+      # loads file metadata, if it's initialized with url or uuid
+      def load
+        initialize(File.info(uuid).entity)
+      end
+
+      # The method to convert a document file to another file
+      # gets (conversion) params [Hash], options (store: Boolean) [Hash], converter [Class]
+      # @returns [File]
+      def convert_document(params = {}, options = {}, converter = Conversion::DocumentConverter)
+        convert_file(params, converter, options)
+      end
+
+      # The method to convert a video file to another file
+      # gets (conversion) params [Hash], options (store: Boolean) [Hash], converter [Class]
+      # @returns [File]
+      def convert_video(params = {}, options = {}, converter = Conversion::VideoConverter)
+        convert_file(params, converter, options)
+      end
+
+      # 'copy' method is used to copy original files or their modified versions to default storage.
+      #
+      # Source files MAY either be stored or just uploaded and MUST NOT be deleted.
+      #
+      # @param [String] source uuid or uploadcare link to file.
+      # @param [Hash] args
+      # @option args [Boolean] :store Whether to store the file
+      # @option args [Boolean] :strip_operations Copies file without transformations (if source has them)
+      # @option args [String] :target points to a target custom storage.
+      # @option args [Boolean] :make_public make files on custom storage available via public links.
+      # @option args [String] :pattern define file naming pattern for the custom storage scenario.
+      #
+      # @see https://uploadcare.com/api-refs/rest-api/v0.5.0/#operation/copyFile
+      def self.copy(source, **args)
+        response = FileClient.new.copy(source: source, **args).success[:result]
+        File.new(response)
+      end
+
+      # Copies file to current project
+      #
+      # source can be UID or full CDN link
+      #
+      # @see .copy
+      def self.local_copy(source, **args)
+        File.copy(source, **args)
+      end
+
+      # copy file to different project
+      #
+      # source can be UID or full CDN link
+      #
+      # @see .copy
+      def self.remote_copy(source, target, **args)
+        File.copy(source: source, target: target, **args)
+      end
+
+      # Instance version of #{copy}. Copies current file.
+      def copy(**args)
+        File.copy(uuid, **args)
+      end
+
+      # Instance version of {internal_copy}
+      def local_copy(**args)
+        File.local_copy(uuid, **args)
+      end
+
+      # Instance version of {external_copy}
+      def remote_copy(target, **args)
+        File.copy(uuid, target: target, **args)
+      end
+
+      private
+
+      def convert_file(params, converter, options = {})
+        raise Uploadcare::Exception::ConversionError, 'The first argument must be a Hash' unless params.is_a?(Hash)
+
+        params_with_symbolized_keys = params.map { |k, v| [k.to_sym, v] }.to_h
+        params_with_symbolized_keys[:uuid] = uuid
+        result = converter.convert(params_with_symbolized_keys, options)
+        result.success? ? File.info(result.value![:result].first[:uuid]) : result
+      end
+    end
+  end
+end

data/lib/uploadcare/entity/file_list.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'uploadcare/entity/file'
+require 'uploadcare/entity/decorator/paginator'
+require 'api_struct'
+
+module Uploadcare
+  module Entity
+    # This serializer returns lists of files
+    #
+    # This is a paginated list, so all pagination methods apply
+    # @see Uploadcare::Entity::Decorator::Paginator
+    class FileList < ApiStruct::Entity
+      include Uploadcare::Entity::Decorator::Paginator
+      client_service Client::FileListClient
+
+      attr_entity :next, :previous, :total, :per_page
+
+      has_entities :results, as: Uploadcare::Entity::File
+      has_entities :result, as: Uploadcare::Entity::File
+
+      # alias for result/results, depending on which API this FileList was initialized from
+      # @return [Array] of [Uploadcare::Entity::File]
+      def files
+        results
+      rescue ApiStruct::EntityError
+        result
+      end
+    end
+  end
+end

data/lib/uploadcare/entity/group.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'uploadcare/entity/file'
+
+module Uploadcare
+  module Entity
+    # Groups serve a purpose of better organizing files in your Uploadcare projects.
+    #
+    # You can create one from a set of files by using their UUIDs.
+    #
+    # @see https://uploadcare.com/docs/api_reference/upload/groups/
+    class Group < Entity
+      client_service RestGroupClient, prefix: 'rest', only: :store
+      client_service GroupClient
+
+      attr_entity :id, :datetime_created, :datetime_stored, :files_count, :cdn_url, :url
+      has_entities :files, as: Uploadcare::Entity::File
+
+      # Remove these lines and bump api_struct version when this PR is accepted:
+      # @see https://github.com/rubygarage/api_struct/pull/15
+      def self.store(uuid)
+        rest_store(uuid)
+      end
+
+      # gets groups's id - even if it's only initialized with cdn_url
+      # @return [String]
+      def id
+        return @entity.id if @entity.id
+
+        id = @entity.cdn_url.gsub('https://ucarecdn.com/', '')
+        id.gsub(%r{/.*}, '')
+      end
+
+      # loads group metadata, if it's initialized with url or id
+      def load
+        initialize(Group.info(id).entity)
+      end
+    end
+  end
+end

data/lib/uploadcare/entity/group_list.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'uploadcare/entity/group'
+require 'uploadcare/entity/decorator/paginator'
+
+module Uploadcare
+  module Entity
+    # List of groups
+    #
+    # @see https://uploadcare.com/docs/api_reference/upload/groups/
+    #
+    # This is a paginated list, so all pagination methods apply
+    # @see Uploadcare::Entity::Decorator::Paginator
+    class GroupList < Entity
+      include Uploadcare::Entity::Decorator::Paginator
+      client_service RestGroupClient, only: :list
+
+      attr_entity :next, :previous, :total, :per_page, :results
+      has_entities :results, as: Group
+
+      alias groups results
+    end
+  end
+end

data/lib/uploadcare/entity/project.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module Entity
+    # This serializer returns info about a project and its data
+    # @see https://uploadcare.com/docs/api_reference/rest/handling_projects/
+    class Project < Entity
+      client_service ProjectClient
+
+      attr_entity :collaborators, :pub_key, :name, :autostore_enabled
+    end
+  end
+end