crowdin-api 1.1.1 → 1.5.0

data/lib/crowdin-api/client/client.rb

@@ -1,82 +1,190 @@
 # frozen_string_literal: true
 
 #
-# The Crowdin::Client library is used for interactions with a crowdin.com website.
+# A wrapper and interface to the Crowdin API. Please visit the Crowdin developers site
+# for a full explanation of what each of the Crowdin api methods expect and perform.
 #
-# == Example
-#
-#  require 'crowdin-api'
-#
-#  crowdin = Crowdin::Client.new do |config|
-#    config.api_token = 'YOUR_API_TOKEN'
-#  end
-#
-#  crowdin.list_projects
+# https://support.crowdin.com/api/v2/
+# https://support.crowdin.com/enterprise/api/
 #
 module Crowdin
+  #
+  # === Example
+  #
+  #  require 'crowdin-api'
+  #
+  #  crowdin = Crowdin::Client.new do |config|
+  #    config.api_token = 'YOUR_API_TOKEN'
+  #  end
+  #
+  #  crowdin.list_projects
+  #
   class Client
-    # A wrapper and interface to the Crowdin api. Please visit the Crowdin developers
-    # site for a full explanation of what each of the Crowdin api methods
-    # expect and perform.
-    #
-    # https://support.crowdin.com/api/v2/
-    #
-    include ApiResources::Languages
-    include ApiResources::Projects
-    include ApiResources::SourceFiles
-    include ApiResources::Storages
-    include ApiResources::TranslationStatus
-    include ApiResources::Translations
-    include ApiResources::Workflows
-    include ApiResources::SourceStrings
+    # Processing API Resources modules to include them to the Client
+    API_RESOURCES_MODULES.each do |module_name|
+      Client.send(:include, Object.const_get("Crowdin::ApiResources::#{module_name}"))
+    end
 
-    include Errors::ApiErrorsRaiser
+    # Processing Error Raisers modules to include them to the Client
+    ERROR_RAISERS_MODULES.each do |module_name|
+      Client.send(:include, Object.const_get("Crowdin::Errors::#{module_name}"))
+    end
 
-    attr_accessor :logger
+    include Web::FetchAllExtensions
 
+    # Config instance that includes configuration options for the Client
     attr_reader :config
+    # Instance with established connection through RestClient to the Crowdin API
     attr_reader :connection
+    # Instance with options and headers for RestClient connection
     attr_reader :options
+    # Logger instance
+    attr_reader :logger
 
     def initialize(&block)
       build_configuration(&block)
 
-      check_logger
-      check_rest_client_proxy
+      update_logger
+      update_rest_client_proxy
 
       build_connection
     end
 
-    def log!(message)
-      !config.logger_enabled? || logger.debug(message)
+    def log(message)
+      !logger_enabled? || logger.debug(message)
     end
 
-    private
+    def logger=(logger)
+      raise_logger_are_not_enabled_error unless logger_enabled?
 
-    def build_configuration
-      @config = Crowdin::Configuration.new
-      yield config if block_given?
+      @logger = logger
+      update_rest_client_logger
     end
 
-    def build_connection
-      @connection ||= ::RestClient::Resource.new(config.base_url, build_options)
+    def enterprise_mode?
+      !!config.organization_domain
     end
 
-    def build_options
-      @options ||= config.options.merge(headers: config.headers)
+    def logger_enabled?
+      config.logger_enabled?
     end
 
-    def set_default_logger
-      require 'logger'
-      @logger ||= Logger.new($stderr)
-    end
+    #
+    # FetchAll options:
+    # * limit, Integer, default: 500 | How many records need to load per one request
+    # * offset, Integer, default: 0 | How many records need to skip
+    # * request_delay, Integer (seconds), default: 0 | Delay between requests
+    #
+    #
+    # Note: Please, specify project_id while Client initialization if you need to use methods that need it within FetchAll
+    #
+    # === Example
+    #
+    #  @crowdin.fetch_all(:list_projects)
+    #
+    # with specified options
+    #
+    #  @crowdin.fetch_all(:list_projects, { limit: 10, request_delay: 1 })
+    #
+    # playing with response per fetch. Note: the block actually don't make any effect to finite result
+    #
+    #  @crowdin.fetch_all(:list_projects, { limit: 10, request_delay: 1 }) { |response| puts response['data'] }
+    #
+    # also you can specify retry configuration to handle some exceptions
+    #
+    # Retry configuration options:
+    # * request_delay, Integer (seconds), default: 0 | Delay between retries
+    # * retries_count, Integer, default: 0
+    # * error_messages, Array
+    #
+    #  @crowdin.fetch_all(:list_projects, {}, { request_delay: 2, retries_count: 3, error_messages: ['401'] })
+    #
+    # fetch all execution will be terminated if response error are same as in error_messages array
+    # otherwise system will retry so many times, as indicated at tries_count
+    #
+    def fetch_all(api_resource, opts = {}, retry_opts = {})
+      unless api_resource.to_s.start_with?('list_')
+        raise(Errors::FetchAllProcessingError, "#{api_resource} method aren't supported for FetchAll")
+      end
 
-    def check_rest_client_proxy
-      ENV['http_proxy'] ? ::RestClient.proxy = ENV['http_proxy'] : false
-    end
+      limit = opts[:limit] || Web::FetchAllExtensions::MAX_ITEMS_COUNT_PER_REQUEST
+      offset = opts[:offset] || 0
+      request_delay = opts[:request_delay] || 0
 
-    def check_logger
-      config.logger_enabled? ? set_default_logger : config.enable_logger = false
+      retry_request_delay = retry_opts[:request_delay] || 0
+      retries_count = retry_opts[:retries_count] || 0
+      retry_error_messages = retry_opts[:error_messages] || []
+
+      result = []
+      loop do
+        response = case api_resource
+        when :list_terms
+          send(api_resource, opts[:glossary_id], { limit: limit, offset: offset }.merge(opts))
+        when :list_file_revisions
+          send(api_resource, opts[:file_id], { limit: limit, offset: offset }.merge(opts))
+        else
+          send(api_resource, { limit: limit, offset: offset }.merge(opts))
+        end
+
+        if response.is_a?(String) && response.match('Something went wrong')
+          if retries_count.positive?
+            retry_error_messages.each do |message|
+              break if response.match(message)
+            end
+
+            retries_count -= 1
+            sleep retry_request_delay
+          else
+            raise(Errors::FetchAllProcessingError, response)
+          end
+        else
+          yield response if block_given?
+          deserialized_response = response['data']
+          result.concat(deserialized_response)
+          offset += deserialized_response.size
+          break if deserialized_response.size < limit
+        end
+
+        sleep request_delay
+      end
+      result
+    rescue StandardError => e
+      raise(Errors::FetchAllProcessingError, "FetchAll wasn't processed. Details - #{e.message}")
     end
+
+    private
+
+      def build_configuration
+        @config = Crowdin::Configuration.new
+        yield config if block_given?
+      end
+
+      def build_connection
+        build_options
+        @connection ||= ::RestClient::Resource.new(config.base_url, options)
+      end
+
+      def build_options
+        @options ||= config.options.merge(headers: config.headers)
+      end
+
+      def set_default_logger
+        require 'logger'
+
+        @logger ||= Logger.new($stdout)
+        update_rest_client_logger
+      end
+
+      def update_rest_client_logger
+        ::RestClient.log = @logger
+      end
+
+      def update_rest_client_proxy
+        ENV['http_proxy'] ? ::RestClient.proxy = ENV.fetch('http_proxy') : false
+      end
+
+      def update_logger
+        config.logger_enabled? ? set_default_logger : config.enable_logger = false
+      end
   end
 end

data/lib/crowdin-api/client/configuration.rb

@@ -5,13 +5,12 @@ module Crowdin
     attr_accessor :api_token
     attr_accessor :project_id
     attr_accessor :organization_domain
+
     attr_accessor :enable_logger
+    alias logger_enabled? enable_logger
 
     attr_reader :target_api_url
 
-    alias logger_enabled?  enable_logger
-    alias enterprise_mode? organization_domain
-
     def initialize
       @target_api_url = '/api/v2'
     end
@@ -20,25 +19,30 @@ module Crowdin
       {
         headers: {},
         timeout: nil,
-        json: true
+        json:    true
       }
     end
 
     def headers
       {
-        'Accept' => 'application/json',
+        'Accept'        => 'application/json',
         'Authorization' => "Bearer #{api_token}",
-        'Content-Type' => 'application/json',
-        'User-Agent' => "crowdin-rb/#{Crowdin::Client::VERSION}/#{RUBY_VERSION}/#{RUBY_PLATFORM}"
+        'Content-Type'  => 'application/json',
+        'User-Agent'    => "crowdin-rb/#{Crowdin::Client::VERSION}/#{RUBY_VERSION}/#{RUBY_PLATFORM}"
       }
     end
 
     def base_url
-      if enterprise_mode?
-        organization_domain.include?('.com') ? organization_domain : "https://#{organization_domain}.api.crowdin.com"
-      else
-        'https://api.crowdin.com'
-      end
+      @base_url ||=
+        if !!organization_domain
+          if organization_domain.include?('.com')
+            "https://#{organization_domain}"
+          else
+            "https://#{organization_domain}.api.crowdin.com"
+          end
+        else
+          'https://api.crowdin.com'
+        end
     end
   end
 end

data/lib/crowdin-api/client/version.rb

@@ -2,6 +2,6 @@
 
 module Crowdin
   class Client
-    VERSION = '1.1.1'
+    VERSION = '1.5.0'
   end
 end

data/lib/crowdin-api/core/errors.rb

@@ -2,6 +2,8 @@
 
 module Crowdin
   module Errors
-    class OnlyForEnterpriseMode < StandardError; end
+    class OnlyForEnterpriseModeError < StandardError; end
+    class LoggerAreNotEnabledError   < StandardError; end
+    class FetchAllProcessingError    < StandardError; end
   end
 end

data/lib/crowdin-api/core/{api_errors_raiser.rb → errors_raisers.rb}

@@ -2,9 +2,29 @@
 
 module Crowdin
   module Errors
+    # Client errors raiser
+    module ClientErrorsRaiser
+      def raise_logger_are_not_enabled_error
+        raise(LoggerAreNotEnabledError, 'Logger are not enabled in your Client configuration, enable it ' \
+                                        'before setting your logger')
+      end
+    end
+
+    # Command-Line Client errors raiser
+    module ClcErrorsRaiser
+      def raise_api_token_is_required_error
+        raise(ArgumentError, '--api-token option is required')
+      end
+
+      def raise_organization_domain_is_required_error
+        raise(ArgumentError, '--organization-domain option is required for Enterprise mode')
+      end
+    end
+
+    # API errors raiser
     module ApiErrorsRaiser
       def raise_only_for_enterprise_mode_error
-        raise(OnlyForEnterpriseMode, 'This method can be called only for Enterprise mode')
+        raise(OnlyForEnterpriseModeError, 'This method can be called only for Enterprise mode')
       end
 
       def raise_project_id_is_required_error
@@ -14,16 +34,6 @@ module Crowdin
       def raise_parameter_is_required_error(parameter)
         raise(ArgumentError, ":#{parameter} is required")
       end
-
-      # crowdin-console errors
-
-      def raise_api_token_is_required_error
-        raise(ArgumentError, '--api-token option is required')
-      end
-
-      def raise_organization_domain_is_required_error
-        raise(ArgumentError, '--organization-domain option is required for Enterprise mode')
-      end
     end
   end
 end

data/lib/crowdin-api/core/fetch_all_extensions.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Crowdin
+  module Web
+    module FetchAllExtensions
+      MAX_ITEMS_COUNT_PER_REQUEST = 500.freeze
+    end
+  end
+end

data/lib/crowdin-api/core/request.rb

@@ -3,116 +3,76 @@
 module Crowdin
   module Web
     class Request
-      attr_reader :client
-
-      def initialize(client, method, path, query = {}, headers = {}, destination = nil)
-        @client      = client
-        @method      = method
-        @full_path   = client.config.target_api_url + path
-        @payload     = perform_payload(query)
-        @headers     = headers
-        @destination = destination
-        @errors      = []
+      attr_reader :connection
+      attr_reader :method
+      attr_reader :payload
+
+      def initialize(connection, method, url, payload = {})
+        @connection = connection[url]
+        @method     = method
+        @payload    = build_payload(payload)
       end
 
-      def perform
-        process_request!
-        process_response!
+      def get?
+        method.eql?(:get)
       end
 
-      private
-
-      def process_request!
-        return @response = client.connection[@full_path].delete        if delete_request?
-        return @response = client.connection[@full_path].get(@payload) if get_request?
-
-        client.connection[@full_path].send(@method, @payload, @headers) { |response, _, _| @response = response }
-      rescue StandardError => error
-        client.log! error
-
-        @errors << "Something went wrong while proccessing request. Details - #{error.class}"
+      def get
+        connection.get(prepare_payload(payload[:params]))
       end
 
-      def process_response!
-        return fetch_errors if @errors.any?
-
-        begin
-          if @response
-            client.log! "args: #{@response.request.args}"
-
-            if @response.body.empty?
-              @response.code
-            else
-              doc = JSON.parse(@response.body)
-
-              client.log! "body: #{doc}"
-
-              data = fetch_response_data(doc)
-
-              @errors.any? ? fetch_errors : data
-            end
-          end
-        rescue StandardError => error
-          client.log! error
-
-          @errors << "Something went wrong while proccessing response. Details - #{error.class}"
-
-          fetch_errors
-        end
+      def delete?
+        method.eql?(:delete)
       end
 
-      def perform_payload(query)
-        return query if query.is_a?(File)
-
-        get_request? ? { params: fetch_cleared_query(query) } : fetch_cleared_query(query).to_json
+      def delete
+        connection.delete
       end
 
-      def download_file(url)
-        download = URI.parse(url).open
-        destination = @destination || download.meta['content-disposition']
-                                              .match(/filename=("?)(.+)\1/)[2]
-
-        IO.copy_stream(download, destination)
-
-        destination
-      rescue StandardError => error
-        client.log! error
+      def process_with_body
+        connection.send(method, prepare_payload(payload[:params]), payload[:headers]) { |response, _, _| response }
+      end
 
-        @errors << "Something went wrong while downloading file. Details - #{error.class}"
+      def post?
+        method.eql?(:post)
       end
+      alias post process_with_body
 
-      def fetch_errors
-        @errors.join(';')
+      def patch?
+        method.eql?(:patch)
       end
+      alias patch process_with_body
 
-      def fetch_response_data(doc)
-        if doc['data'].is_a?(Hash) && doc['data']['url'] && doc['data']['url'].include?('response-content-disposition')
-          download_file(doc['data']['url'])
-        else
-          doc
-        end
+      def put?
+        method.eql?(:put)
       end
+      alias put process_with_body
 
-      def fetch_cleared_query(query)
-        case query
-        when Array
-          query.map do |el|
-            el.reject { |_, value| value.nil? }
-          end.reject(&:empty?)
-        when Hash
-          query.reject { |_, value| value.nil? }
-        else
-          query
+      private
+
+        def build_payload(payload)
+          %i[params headers].each do |key|
+            payload[key] ||= {}
+          end
+          payload
         end
-      end
 
-      def get_request?
-        @method.eql?(:get)
-      end
+        def prepare_payload(params)
+          return params if params.is_a?(File)
 
-      def delete_request?
-        @method.eql?(:delete)
-      end
+          get? ? { params: fetch_cleared_params(params) } : fetch_cleared_params(params).to_json
+        end
+
+        def fetch_cleared_params(params)
+          case params
+          when Array
+            params.map { |el| el.reject { |_, value| value.nil? } }.reject(&:empty?)
+          when Hash
+            params.reject { |_, value| value.nil? }
+          else
+            params
+          end
+        end
     end
   end
 end

data/lib/crowdin-api/core/send_request.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Crowdin
+  module Web
+    class SendRequest
+      attr_reader :request
+
+      def initialize(request, file_destination = nil)
+        @request          = request
+        @file_destination = file_destination
+        @errors           = []
+      end
+
+      def perform
+        parse_response(process_request)
+      end
+
+      private
+
+        def process_request
+          request.send(request.method)
+        rescue StandardError => e
+          @errors << "Something went wrong while request processing. Details - #{e.message}"
+        end
+
+        def parse_response(response)
+          return @errors.join('; ') if @errors.any?
+
+          begin
+            if response
+              if response.body.empty?
+                response.code
+              else
+                parsed_body = JSON.parse(response.body)
+                parsed_response = fetch_response_data(parsed_body)
+
+                @errors.any? ? @errors.join('; ') : parsed_response
+              end
+            end
+          rescue StandardError => e
+            @errors << "Something went wrong while response processing. Details - #{e.message}"
+            @errors.join('; ')
+          end
+        end
+
+        def fetch_response_data(doc)
+          if doc['data'].is_a?(Hash) && doc['data']['url'] && doc['data']['url'].include?('response-content-disposition')
+            download_file(doc['data']['url'])
+          else
+            doc
+          end
+        end
+
+        def download_file(url)
+          download    = URI.parse(url).open
+          destination = @file_destination || download.meta['content-disposition']
+                                                     .match(/filename=("?)(.+)\1/)[2]
+
+          IO.copy_stream(download, destination)
+
+          destination
+        rescue StandardError => e
+          @errors << "Something went wrong while downloading file. Details - #{e.message}"
+        end
+    end
+  end
+end

data/lib/crowdin-api.rb

@@ -1,5 +1,16 @@
 # frozen_string_literal: true
 
+module Crowdin
+  # API Resources modules
+  API_RESOURCES_MODULES = %i[Storages Languages Projects Workflows SourceFiles Translations SourceStrings
+                             StringTranslations StringComments Screenshots Glossaries TranslationMemory
+                             MachineTranslationEngines Reports Tasks Users Teams Vendors Webhooks
+                             Dictionaries Distributions Labels TranslationStatus Bundles].freeze
+
+  # Error Raisers modules
+  ERROR_RAISERS_MODULES = %i[ApiErrorsRaiser ClientErrorsRaiser].freeze
+end
+
 # Libs
 require 'json'
 require 'open-uri'
@@ -7,20 +18,19 @@ require 'rest-client'
 
 # Core modules
 require 'crowdin-api/core/errors'
-require 'crowdin-api/core/api_errors_raiser'
+require 'crowdin-api/core/errors_raisers'
 require 'crowdin-api/core/request'
+require 'crowdin-api/core/send_request'
+require 'crowdin-api/core/fetch_all_extensions'
 
-# Api modules
-require 'crowdin-api/api-resources/languages'
-require 'crowdin-api/api-resources/projects'
-require 'crowdin-api/api-resources/source_files'
-require 'crowdin-api/api-resources/storages'
-require 'crowdin-api/api-resources/translation_status'
-require 'crowdin-api/api-resources/translations'
-require 'crowdin-api/api-resources/workflows'
-require 'crowdin-api/api-resources/source_strings'
+# API modules
+Crowdin::API_RESOURCES_MODULES.each do |api_resource|
+  require "crowdin-api/api_resources/#{api_resource.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase}"
+rescue LoadError
+  # Ignored
+end
 
-# Client
+# Client modules
 require 'crowdin-api/client/version'
 require 'crowdin-api/client/configuration'
 require 'crowdin-api/client/client'