uploadcare-ruby 2.1.1 → 3.1.0.pre.rc1

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/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/document_converter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module Entity
+    # This serializer lets a user convert uploaded documents
+    # @see https://uploadcare.com/api-refs/rest-api/v0.6.0/#operation/documentConvert
+    class DocumentConverter < Entity
+      client_service Conversion::DocumentConversionClient
+      # Converts documents
+      #
+      # @param doc_params [Array] of hashes with params or [Hash]
+      # @option options [Boolean] :store (false) whether to store file on servers.
+      def self.convert(doc_params, **options)
+        params = doc_params.is_a?(Hash) ? [doc_params] : doc_params
+        Conversion::DocumentConversionClient.new.convert_many(params, **options)
+      end
+
+      # Returns a status of document conversion job
+      #
+      # @param token [Integer, String] token obtained from a server in convert method
+      def self.status(token)
+        Conversion::DocumentConversionClient.new.get_conversion_status(token)
+      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,81 @@
+# 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
+      # @return [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
+
+      # '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
+    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

data/lib/uploadcare/entity/uploader.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module Entity
+    # This serializer lets user upload files by various means, and usually returns an array of files
+    # @see https://uploadcare.com/api-refs/upload-api/#tag/Upload
+    class Uploader < Entity
+      client_service UploaderClient
+      client_service MultipartUploaderClient, only: :upload, prefix: :multipart
+
+      attr_entity :files
+      has_entities :files, as: Uploadcare::Entity::File
+
+      # Upload file or group of files from array, File, or url
+      #
+      # @param object [Array], [String] or [File]
+      # @param [Hash] options options for upload
+      # @option options [Boolean] :store (false) whether to store file on servers.
+      def self.upload(object, **options)
+        if big_file?(object)
+          upload_big_file(object, **options)
+        elsif file?(object)
+          upload_file(object, **options)
+        elsif object.is_a?(Array)
+          upload_files(object, **options)
+        elsif object.is_a?(String)
+          upload_from_url(object, **options)
+        else
+          raise ArgumentError, "Expected input to be a file/Array/URL, given: `#{object}`"
+        end
+      end
+
+      # upload single file
+      def self.upload_file(file, **options)
+        response = UploaderClient.new.upload_many([file], **options)
+        Uploadcare::Entity::File.info(response.success.to_a.flatten[-1])
+      end
+
+      # upload multiple files
+      def self.upload_files(arr, **options)
+        response = UploaderClient.new.upload_many(arr, **options)
+        response.success.map { |pair| Uploadcare::Entity::File.new(uuid: pair[1], original_filename: pair[0]) }
+      end
+
+      # upload file of size above 10mb (involves multipart upload)
+      def self.upload_big_file(file, **_options)
+        response = MultipartUploaderClient.new.upload(file)
+        Uploadcare::Entity::File.new(response.success)
+      end
+
+      # upload files from url
+      # @param url [String]
+      def self.upload_from_url(url, **options)
+        response = UploaderClient.new.upload_from_url(url, **options)
+        return response.success[:token] unless response.success[:files]
+
+        response.success[:files].map { |file_data| Uploadcare::Entity::File.new(file_data) }
+      end
+
+      class << self
+        private
+
+        # check if object is a file
+        def file?(object)
+          object.respond_to?(:path) && ::File.exist?(object.path)
+        end
+
+        # check if object needs to be uploaded using multipart upload
+        def big_file?(object)
+          file?(object) && object.size >= Uploadcare.config.multipart_size_threshold
+        end
+      end
+    end
+  end
+end

data/lib/uploadcare/entity/video_converter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Uploadcare
+  module Entity
+    # This serializer lets a user convert uploaded videos, and usually returns an array of results
+    # @see https://uploadcare.com/api-refs/rest-api/v0.6.0/#operation/videoConvert
+    class VideoConverter < Entity
+      client_service Conversion::VideoConversionClient
+      # Converts video files
+      #
+      # @param doc_params [Array] of hashes with params or [Hash]
+      # @option options [Boolean] :store (false) whether to store file on servers.
+      def self.convert(video_params, **options)
+        params = video_params.is_a?(Hash) ? [video_params] : video_params
+        Conversion::VideoConversionClient.new.convert_many(params, **options)
+      end
+
+      # Returns a status of video conversion job
+      #
+      # @param token [Integer, String] token obtained from a server in convert method
+      def self.status(token)
+        Conversion::VideoConversionClient.new.get_conversion_status(token)
+      end
+    end
+  end
+end