heartland-retail 5.0.0

data/lib/heartland/client/errors.rb

@@ -0,0 +1,17 @@
+module HeartlandRetail
+  class Client
+    ##
+    # API request failure
+    class RequestFailed < RuntimeError
+      attr_accessor :response
+    end
+
+    ##
+    # Authorization failure
+    class AuthFailed < RequestFailed; end
+
+    ##
+    # Error parsing the response body
+    class BodyError < RequestFailed; end
+  end
+end

data/lib/heartland/client/resource.rb

@@ -0,0 +1,215 @@
+require_relative 'collection'
+
+module HeartlandRetail
+  class Client
+    ##
+    # An representation of an API resource identified by a URI. Allows
+    # triggering API calls via HTTP methods. Allows constructing new resources
+    # in a chained style by calling the methods that manipulate the URI and
+    # return a new resource.
+    #
+    # @example Chaining
+    #   new_resource = resource.
+    #     filter(:field => 'value').
+    #     sort(:id).
+    #     embed(:related_resource)
+    #
+    # Resources are usually constructed via the Client#[] method.
+    class Resource
+      ##
+      # The resource's URI.
+      #
+      # @return [Addressable::URI]
+      attr_reader :uri
+
+      ##
+      # The underlying HeartlandRetail Client.
+      #
+      # @return [Client]
+      attr_reader :client
+
+      ##
+      # @param [HeartlandRetail::Client] client
+      # @param [Addressable::URI, #to_s] uri
+      def initialize(client, uri_or_path)
+        @client = client
+        @uri = normalize_uri(uri_or_path)
+      end
+
+      ##
+      # Performs a HEAD request against the resource's URI and returns the Response.
+      #
+      # @return [Response]
+      def head(headers=false); call_client(:head, headers); end
+
+      ##
+      # Performs a HEAD request against the resource's URI. Returns the Response
+      # on success and raises a RequestFailed on failure..
+      #
+      # @raise [RequestFailed] On error response
+      #
+      # @return [Response]
+      def head!(headers=false); call_client(:head!, headers); end
+
+      ##
+      # Performs a GET request against the resource's URI and returns the Response.
+      #
+      # @return [Response]
+      def get(headers=false); call_client(:get, headers); end
+
+      ##
+      # Performs a GET request against the resource's URI. Returns the Response
+      # on success and raises a RequestFailed on failure.
+      #
+      # @raise [RequestFailed] On error response
+      #
+      # @return [Response]
+      def get!(headers=false); call_client(:get!, headers); end
+
+      ##
+      # Performs a DELETE request against the resource's URI and returns the Response.
+      #
+      # @return [Response]
+      def delete(headers=false); call_client(:delete, headers); end
+
+      ##
+      # Performs a DELETE request against the resource's URI. Returns the Response
+      # on success and raises a RequestFailed on failure.
+      #
+      # @raise [RequestFailed] On error response
+      #
+      # @return [Response]
+      def delete!(headers=false); call_client(:delete!, headers); end
+
+      ##
+      # Performs a PUT request against the resource's URI and returns the Response.
+      #
+      # @return [Response]
+      def put(body, headers=false); call_client(:put, body, headers); end
+
+      ##
+      # Performs a PUT request against the resource's URI. Returns the Response
+      # on success and raises a RequestFailed on failure.
+      #
+      # @raise [RequestFailed] On error response
+      #
+      # @return [Response]
+      def put!(body, headers=false); call_client(:put!, body, headers); end
+
+      ##
+      # Performs a POST request against the resource's URI and returns the Response.
+      #
+      # @return [Response]
+      def post(body, headers=false); call_client(:post, body, headers); end
+
+      ##
+      # Performs a POST request against the resource's URI. Returns the Response
+      # on success and raises a RequestFailed on failure.
+      #
+      # @raise [RequestFailed] On error response
+      #
+      # @return [Response]
+      def post!(body, headers=false); call_client(:post!, body, headers); end
+
+      ##
+      # Returns a new subordinate resource with the given sub-path.
+      #
+      # @return [Resource]
+      def [](uri)
+        clone(self.uri.subpath(uri))
+      end
+
+      ##
+      # If called with +params+ as a +Hash+:
+      #
+      # Returns a new resource where the given query hash
+      # is merged with the existing query string parameters.
+      #
+      # If called with no arguments:
+      #
+      # Returns the resource's current query string parameters and values
+      # as a hash.
+      #
+      # @return [Resource, Hash]
+
+      ##
+      # @overload query(params)
+      #   Returns a new resource where the given +params+ hash of parameter
+      #   names and values is merged with the existing query string parameters.
+      #
+      #   @param [Hash] params New query string parameters
+      #   @return [Resource]
+      #
+      # @overload query()
+      #   Returns the resource's current query string parameters and values
+      #   as a hash.
+      #
+      #   @return [Hash]
+      def query(params=nil)
+        if params
+          uri = self.uri.dup
+          uri.merge_query_values!(params)
+          clone(uri)
+        else
+          self.uri.query_values || {}
+        end
+      end
+
+      alias params query
+
+      ##
+      # Returns a cloned copy of the resource with the same URI.
+      #
+      # @return [Resource]
+      def clone(uri=nil)
+        self.class.new(client, uri ? uri : self.uri)
+      end
+
+      ##
+      # Returns a new resource with the given embeds added to the query string
+      # (via _include params).
+      #
+      # @return [Resource]
+      def embed(*embeds)
+        embeds = (query['_include'] || []) + embeds
+        query('_include' => embeds)
+      end
+
+      ##
+      # Returns true if a HEAD request to the resource returns a successful response,
+      # false if it returns 404, otherwise raises an exception.
+      #
+      # @raise [RequestFailed] If response is not success or 404
+      #
+      # @return [Boolean]
+      def exists?
+        response = head
+        return true if response.success?
+        return false if response.status == 404
+        error = RequestFailed.new "Request during call to 'exists?' resulted in non-404 error."
+        error.response = response
+        raise error
+      end
+
+      include Collection
+
+      private
+
+      ##
+      # Normalizes the URI or path given to a URI
+      def normalize_uri(uri_or_path)
+        uri = URI.parse(uri_or_path)
+        return uri if uri.to_s.start_with?(client.base_uri.to_s)
+        path = uri_or_path.to_s.start_with?('/') ? uri_or_path : "/#{uri_or_path}"
+        path.to_s.gsub!(/^#{client.base_uri.to_s}|^#{client.base_uri.path}/, '')
+        URI.parse("#{client.base_uri}#{path}")
+      end
+
+      ##
+      # Calls a client method, passing the URI as the first argument.
+      def call_client(method, *args, &block)
+        client.__send__(method, *args.unshift(uri), &block)
+      end
+    end
+  end
+end

data/lib/heartland/client/response.rb

@@ -0,0 +1,84 @@
+module HeartlandRetail
+  class Client
+    ##
+    # An API response including body, headers, and status information.
+    class Response
+      ##
+      # @param [Response] response
+      # @param [Client] client
+      def initialize(response, client)
+        @response = response
+        @client = client
+      end
+
+      ##
+      # Returns the corresponding key from "body".
+      def [](key)
+        body[key]
+      end
+
+      ##
+      # Returns the raw response body as a String.
+      #
+      # @return [String] The raw response body
+      def raw_body
+        @response.body
+      end
+
+      ##
+      # Returns the parsed response body as a Body object.
+      #
+      # @raise [BodyError] If the body is not parseable
+      #
+      # @return [Body] The parsed response body
+      def body
+        @data ||= parse_body
+      end
+
+      ##
+      # Returns true if the request was successful, else false.
+      #
+      # @return [Boolean]
+      def success?
+        status < 400
+      end
+
+      ##
+      # Delegates missing methods to the underlying Faraday::Response.
+      #
+      # @see https://www.rubydoc.info/gems/faraday/Faraday/Response Faraday::Response docs
+      def method_missing(method, *args, &block)
+        @response.respond_to?(method) ? @response.__send__(method, *args, &block) : super
+      end
+
+      ##
+      # If the response included a 'Location' header, returns a new Resource with
+      # a URI set to its value, else nil.
+      #
+      # @return [Resource]
+      def resource
+        if location = headers['Location']
+          @client[headers['Location']]
+        else
+          nil
+        end
+      end
+
+      protected
+
+      def parse_body
+        if @response.body.empty?
+          raise BodyError,
+            "Response body is empty. (Hint: If you just created a new resource, try: response.resource.get)" 
+        end
+
+        begin
+          data = JSON.parse(@response.body)
+          Body.new data
+        rescue JSON::ParserError => e
+          raise BodyError, "Can't parse response body. (Hint: Try the raw_body method.)"
+        end
+      end
+    end
+  end
+end

data/lib/heartland/client/uri.rb

@@ -0,0 +1,117 @@
+require 'uri'
+
+module HeartlandRetail
+  class Client
+    ##
+    # A wrapper around URI
+    class URI
+      ##
+      # Returns a URI object based on the parsed string.
+      #
+      # @return [URI]
+      def self.parse(value)
+        return value.dup if value.is_a?(self)
+        new(::URI.parse(value.to_s))
+      end
+
+      ##
+      # Creates a new URI object from an Addressable::URI
+      #
+      # @return [URI]
+      def initialize(uri)
+        @uri = uri
+      end
+
+      ##
+      # Clones the URI object
+      #
+      # @return [URI]
+      def dup
+        self.class.new(@uri.dup)
+      end
+
+      ##
+      # Returns a new URI with the given subpath appended to it. Ensures a single
+      # forward slash between the URI's path and the given subpath.
+      #
+      # @return [URI]
+      def subpath(subpath)
+        uri = dup
+        uri.path = "#{path}/" unless path.end_with?('/')
+        uri.path = uri.path + ::URI.encode(subpath.to_s.gsub(/^\//, ''))
+        uri
+      end
+
+      ##
+      # Merges the given hash of query string parameters and values with the URI's
+      # existing query string parameters (if any).
+      def merge_query_values!(values)
+        old_query_values = self.query_values || {}
+        self.query_values = old_query_values.merge(normalize_query_hash(values))
+      end
+
+      ##
+      # Checks if supplied URI matches current URI
+      #
+      # @return [boolean]
+      def ==(other_uri)
+        return false unless other_uri.is_a?(self.class)
+        uri == other_uri.__send__(:uri)
+      end
+
+      ##
+      # Overwrites the query using the supplied query values
+      def query_values=(values)
+        self.query = ::URI.encode_www_form(normalize_query_hash(values).sort)
+      end
+
+      ##
+      # Returns a hash of query string parameters and values
+      #
+      # @return [hash]
+      def query_values
+        return nil if query.nil?
+        ::URI.decode_www_form(query).each_with_object({}) do |(k, v), hash|
+          if k.end_with?('[]')
+            k.gsub!(/\[\]$/, '')
+            hash[k] = Array(hash[k]) + [v]
+          else
+            hash[k] = v
+          end
+        end
+      end
+
+      private
+
+      attr_reader :uri
+
+      def self.delegate_and_wrap(*methods)
+        methods.each do |method|
+          define_method(method) do |*args, &block|
+            @uri.__send__(method, *args, &block)
+          end
+        end
+      end
+
+      delegate_and_wrap(
+        :path, :path=, :to_s, :query, :query=
+      )
+
+      def normalize_query_hash(hash)
+        hash.inject({}) do |copy, (k, v)|
+          k = "#{k}[]" if v.is_a?(Array) && !k.to_s.end_with?('[]')
+          copy[k.to_s] = normalize_query_value(v)
+          copy
+        end
+      end
+
+      def normalize_query_value(value)
+        case value
+        when Hash then normalize_query_hash(value)
+        when true, false then value.to_s
+        when Array then value.uniq
+        else value end
+      end
+    end
+  end
+end

data/spec/heartland/client/body_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+describe HeartlandRetail::Client::Body do
+  let(:hash) { {"key1" => "val1", "key2" => {"subkey1" => "subval1"}} }
+  let(:body) { HeartlandRetail::Client::Body.new(hash)}
+
+  describe "[]" do
+    it "should support string keys" do
+      expect(body["key1"]).to eq("val1")
+    end
+
+    it "should support symbol keys" do
+      expect(body[:key1]).to eq("val1")
+    end
+  end
+
+  describe "nested hashes" do
+    it "should support nested indifferent access" do
+      expect(body[:key2][:subkey1]).to eq("subval1")
+      expect(body['key2']['subkey1']).to eq("subval1")
+      expect(body[:key2]['subkey1']).to eq("subval1")
+      expect(body['key2'][:subkey1]).to eq("subval1")
+    end
+  end
+
+  describe "to_hash" do
+    it "should return the original hash" do
+      expect(body.to_hash).to be === hash
+    end
+  end
+end