groupdocs 0.1.0

data/lib/groupdocs/api/helpers/rest_helper.rb

@@ -0,0 +1,89 @@
+module GroupDocs
+  module Api
+    module Helpers
+      module REST
+
+        DEFAULT_HEADERS = {
+          accept:         'application/json',
+          content_length: 0
+        }
+
+        private
+
+        #
+        # Prepares headers, method and payload for request.
+        #
+        # @api private
+        #
+        def prepare_request
+          if options[:headers].is_a?(Hash)
+            options[:headers].merge!(DEFAULT_HEADERS)
+          else
+            options[:headers] = DEFAULT_HEADERS.dup
+          end
+
+          options[:method] = options[:method].downcase
+
+          if options[:request_body] && !options[:request_body].is_a?(Object::File)
+            options[:request_body] = options[:request_body].to_json
+            options[:headers][:content_type]= 'application/json'
+            options[:headers][:content_length] = options[:request_body].length
+          end
+        end
+
+        #
+        # Sends request to API server.
+        #
+        # @api private
+        #
+        def send_request
+          self.response = case options[:method]
+            when :get, :download
+              resource[options[:path]].get(options[:headers])
+            when :post
+              resource[options[:path]].post(options[:request_body], options[:headers])
+            when :put
+              resource[options[:path]].put(options[:request_body], options[:headers])
+            when :delete
+              resource[options[:path]].delete(options[:headers])
+            else
+              raise GroupDocs::Errors::UnsupportedMethodError, "Unsupported HTTP method: #{options[:method].inspect}"
+          end
+        end
+
+        #
+        # Parses response from API server.
+        #
+        # @api private
+        #
+        def parse_response
+          # for DOWNLOAD requests, just return response
+          if options[:method] == :download
+            response
+          # for all other requests, parse JSON
+          else
+            json = JSON.parse(response, symbolize_names: true)
+            json[:status] == 'Ok' ? json[:result] : raise_bad_request_error(json)
+          end
+        end
+
+        #
+        # @raise [GroupDocs::Errors::BadResponseError]
+        # @api private
+        #
+        def raise_bad_request_error(json)
+          raise GroupDocs::Errors::BadResponseError, <<-ERR
+            Bad response!
+            Request method: #{options[:method].upcase}
+            Request URL: #{resource[options[:path]]}
+            Request body: #{options[:request_body]}
+            Status: #{json[:status]}
+            Error message: #{json[:error_message]}
+            Response body: #{response}
+          ERR
+        end
+
+      end # Request
+    end # Helpers
+  end # Api
+end # GroupDocs

data/lib/groupdocs/api/helpers/status_helper.rb

@@ -0,0 +1,48 @@
+module GroupDocs
+  module Api
+    module Helpers
+      module Status
+
+        STATUSES = {
+          draft:      -1,
+          pending:     0,
+          scheduled:   1,
+          in_progress: 2,
+          completed:   3,
+          postponed:   4,
+          archived:    5,
+        }
+
+        # @attr [Symbol] status
+        attr_accessor :status
+
+        #
+        # Sets status of the entity.
+        #
+        # @return [Symbol]
+        #
+        def status
+          parse_status(@status)
+        end
+
+        private
+
+        #
+        # Converts status from/to human-readable format.
+        #
+        # @param [Integer, Symbol] status
+        # @return [Symbol, Integer]
+        # @api private
+        #
+        def parse_status(status)
+          if status.is_a?(Integer)
+            STATUSES.invert[status]
+          else
+            STATUSES[status]
+          end or raise ArgumentError, "Unknown status: #{status.inspect}."
+        end
+
+      end # Status
+    end # Helpers
+  end # Api
+end # GroupDocs

data/lib/groupdocs/api/helpers/url_helper.rb

@@ -0,0 +1,89 @@
+require 'base64'
+require 'hmac-sha1'
+require 'uri'
+require 'cgi'
+
+module GroupDocs
+  module Api
+    module Helpers
+      module URL
+
+        #
+        # Appends path with parameters.
+        #
+        # @param [Hash] params
+        #
+        def add_params(params)
+          params.each do |param, value|
+            value = value.join(?,) if value.is_a?(Array)
+            options[:path] << "#{separator}#{param}=#{value}"
+          end
+        end
+
+        private
+
+        #
+        # Parses path replacing {client_id} with real one.
+        #
+        # @api private
+        #
+        def parse_path
+          options[:path] = options[:path].sub(/\{\{client_id\}\}/, client_id)
+        end
+
+        #
+        # URL encodes path.
+        #
+        # @api private
+        #
+        def url_encode_path
+          options[:path] = URI.escape(options[:path])
+        end
+
+        #
+        # Adds signature to path.
+        #
+        # @api private
+        #
+        def sign_url
+          # calculate a hash of the path with private key
+          hash = HMAC::SHA1.new(private_key)
+          hash << options[:path]
+          hash = hash.digest
+          # convert hash to base64
+          hash = Base64.strict_encode64(hash)
+          # remove trailing '='
+          hash = hash.gsub(/=*$/, '')
+          # URL encode hash
+          hash = CGI.escape(hash)
+          # covert all hexademical characters to upper case
+          hash = hash.gsub(/(%[A-Fa-f0-9]{1,2})/) { |group| group.upcase }
+
+          options[:path] << "#{separator}signature=#{hash}"
+        end
+
+        #
+        # Returns separator for GET parameters.
+        #
+        # @return [String] Either ? or &
+        # @api private
+        #
+        def separator
+          options[:path].include?('?') ? '&' : '?'
+        end
+
+        #
+        # Prepends path with version number if it's set.
+        #
+        # @api private
+        #
+        def prepend_version
+          if GroupDocs.api_version
+            options[:path] = "/v#{GroupDocs.api_version}#{options[:path]}"
+          end
+        end
+
+      end # Query
+    end # Helpers
+  end # Api
+end # GroupDocs

data/lib/groupdocs/api/request.rb

@@ -0,0 +1,73 @@
+require 'rest-client'
+require 'json'
+require 'groupdocs/api/helpers'
+
+module GroupDocs
+  module Api
+    class Request
+
+      include GroupDocs::Api::Helpers::Access
+      include GroupDocs::Api::Helpers::URL
+      include GroupDocs::Api::Helpers::REST
+
+      # @attr_reader [RestClient::Resource] resource Entry point for all API requests
+      attr_reader   :resource
+      # @attr [String] response Response from server in JSON format
+      attr_accessor :response
+      # @attr [Hash] options Hash of options
+      attr_accessor :options
+      # @attr [Hash] access Hash of access credentials
+      attr_accessor :access
+
+      #
+      # Creates new API request.
+      #
+      # @example
+      #   api = GroupDocs::Api::Request.new do |request|
+      #     request[:method] = :POST
+      #     request[:path] = "/storage/#{GroupDocs.client_id}/info"
+      #   end
+      #
+      # @param [Hash] options
+      # @option options [Symbol] :method HTTP method. One of :GET, :DOWNLOAD, :POST, :PUT or :DELETE.
+      # @option options [String] :path Path to send request to
+      # @option options [Hash] :headers Additional HTTP headers
+      # @option options [Hash] :access Access credentials hash
+      # @option options [Hash, File] :request_body Payload. If hash, will be converted to JSON, if File, will be send as is.
+      #
+      # @yieldparam [Hash] options
+      #
+      def initialize(options = {}, &blk)
+        @options = options
+        yield @options if block_given?
+        @options[:access] ||= {}
+        @resource = RestClient::Resource.new(GroupDocs.api_server)
+      end
+
+      #
+      # Executes API request to server.
+      #
+      # It performs the following actions step by step:
+      #   * Parses path (i.e. replaces client ID)
+      #   * Prepends path with version if it's set
+      #   * URL encodes path
+      #   * Signs URL
+      #   * Prepare request (add headers, converts payload to JSON, etc.)
+      #   * Sends request to server
+      #   * Parses response
+      #
+      # @return [Hash, String] Parsed response
+      #
+      def execute!
+        parse_path
+        prepend_version
+        url_encode_path
+        sign_url
+        prepare_request
+        send_request
+        parse_response
+      end
+
+    end # Request
+  end # Api
+end # GroupDocs

data/lib/groupdocs/api/sugar/lookup.rb

@@ -0,0 +1,48 @@
+module GroupDocs
+  module Api
+    module Sugar
+      module Lookup
+
+        #
+        # Returns first object matching given options.
+        #
+        # @param [Symbol] attribute
+        # @param [Integer, String, Regexp] value
+        # @param [Hash] access Access credentials
+        # @option access [String] :client_id
+        # @option access [String] :private_key
+        # @return [GroupDocs::Api::Entity] Matching entity
+        #
+        def find!(attribute, value, access = {})
+          find_all!(attribute, value, access).first
+        end
+
+        #
+        # Returns all objects matching given options.
+        #
+        # Each entity has to implement #all! method for this to work.
+        #
+        # @param [Symbol] attribute
+        # @param [Integer, String, Regexp] value
+        # @param [Hash] access Access credentials
+        # @option access [String] :client_id
+        # @option access [String] :private_key
+        # @return [Array] Array of matching entities
+        #
+        # @raise [NoMethodError] if extending class does not implement #all! class method.
+        #
+        def find_all!(attribute, value, access = {})
+          respond_to?(:all!) or raise NoMethodError, "#{self}.all! is not implemented - aborting."
+
+          all!('/', access).select do |object|
+            case value
+            when Regexp then object.send(attribute) =~ value
+            else object.send(attribute) == value
+            end
+          end
+        end
+
+      end # Lookup
+    end # Sugar
+  end # Api
+end # GroupDocs

data/lib/groupdocs/datasource.rb

@@ -0,0 +1,162 @@
+module GroupDocs
+  class DataSource < GroupDocs::Api::Entity
+
+    require 'groupdocs/datasource/field'
+
+    #
+    # Returns datasource by given identifier.
+    #
+    # @param [Integer] id
+    # @param [Hash] options
+    # @option options [Array] :field Array of field names to be returned. All by default
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    # @return [GroupDocs::DataSource, nil]
+    #
+    def self.get!(id, options = {}, access = {})
+      api = GroupDocs::Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :GET
+        request[:path] = "/merge/{{client_id}}/datasources/#{id}"
+      end
+      api.add_params(options)
+      json = api.execute!
+
+      GroupDocs::DataSource.new(json[:datasource])
+    rescue GroupDocs::Errors::BadResponseError
+      nil
+    end
+
+    # @attr [Integer] id
+    attr_accessor :id
+    # @attr [String] descr
+    attr_accessor :descr
+    # @attr [Integer] questionnaire_id
+    attr_accessor :questionnaire_id
+    # @attr [Time] created_on
+    attr_accessor :created_on
+    # @attr [Time] modified_on
+    attr_accessor :modified_on
+    # @attr [Array<GroupDocs::DataSource::Field>] fields
+    attr_accessor :fields
+
+    # Human-readable accessors
+    alias_method :description,  :descr
+    alias_method :description=, :descr=
+
+    #
+    # Converts timestamp which is return by API server to Time object.
+    #
+    # @return [Time]
+    #
+    def created_on
+      Time.at(@created_on)
+    end
+
+    #
+    # Converts timestamp which is return by API server to Time object.
+    #
+    # @return [Time]
+    #
+    def modified_on
+      Time.at(@modified_on)
+    end
+
+    #
+    # Converts each field to GroupDocs::DataSource::Field object.
+    #
+    # @param [Array<GroupDocs::DataSource::Field, Hash>] fields
+    #
+    def fields=(fields)
+      if fields
+        @fields = fields.map do |field|
+          if field.is_a?(GroupDocs::DataSource::Field)
+            field
+          else
+            GroupDocs::DataSource::Field.new(field)
+          end
+        end
+      end
+    end
+
+    #
+    # Adds field to datasource.
+    #
+    # @param [GroupDocs::DataSource::Field] question
+    # @raise [ArgumentError] if field is not GroupDocs::DataSource::Field object
+    #
+    def add_field(field)
+      field.is_a?(GroupDocs::DataSource::Field) or raise ArgumentError,
+        "Field should be GroupDocs::DataSource::Field object, received: #{field.inspect}"
+
+      @fields ||= Array.new
+      @fields << field
+    end
+
+    #
+    # Adds datasource.
+    #
+    # @example
+    #   field = GroupDocs::DataSource::Field.new(field: 'test', values: %w(test test))
+    #   datasource = GroupDocs::DataSource.new
+    #   datasource.add_field(field)
+    #   datasource.add!
+    #
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    #
+    def add!(access = {})
+      json = GroupDocs::Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :POST
+        request[:path] = '/merge/{{client_id}}/datasources'
+        request[:request_body] = to_hash
+      end.execute!
+
+      self.id = json[:datasource_id]
+    end
+
+    #
+    # Updates datasource.
+    #
+    # @example
+    #   field = GroupDocs::DataSource::Field.new(field: 'test', values: %w(test test))
+    #   datasource = GroupDocs::DataSource.get!(180)
+    #   datasource.add_field(field)
+    #   datasource.update!
+    #
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    #
+    def update!(access = {})
+      GroupDocs::Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :PUT
+        request[:path] = "/merge/{{client_id}}/datasources/#{id}"
+        request[:request_body] = to_hash
+      end.execute!
+    end
+
+    #
+    # Removes datasource.
+    #
+    # @param [Hash] access Access credentials
+    # @option access [String] :client_id
+    # @option access [String] :private_key
+    #
+    def remove!(access = {})
+      GroupDocs::Api::Request.new do |request|
+        request[:access] = access
+        request[:method] = :DELETE
+        request[:path] = "/merge/{{client_id}}/datasources/#{id}"
+      end.execute!
+    # TODO: fix this in API
+    rescue RestClient::BadRequest
+      nil
+    end
+
+  end # DataSource
+end # GroupDocs