springboard-retail 4.0.0

data/lib/springboard/client/body.rb

@@ -0,0 +1,12 @@
+require 'hashie'
+
+module Springboard
+  class Client
+    ##
+    # An indifferent Hash to represent parsed response bodies.
+    #
+    # @see http://rdoc.info/github/intridea/hashie/Hashie/Mash See the Hashie::Mash docs for usage details
+    class Body < ::Hashie::Mash
+    end
+  end
+end

data/lib/springboard/client/collection.rb

@@ -0,0 +1,108 @@
+module Springboard
+  class Client
+    ##
+    # Mixin provides {Resource} with special methods for convenient interaction
+    # with collection resources.
+    module Collection
+      include ::Enumerable
+
+      ##
+      # Iterates over all results from the collection and yields each one to
+      # the block, fetching pages as needed.
+      #
+      # @raise [RequestFailed]
+      def each(&block)
+        call_client(:each, &block)
+      end
+
+      ##
+      # Iterates over each page of results and yields the page to the block,
+      # fetching as needed.
+      #
+      # @raise [RequestFailed]
+      def each_page(&block)
+        call_client(:each_page, &block)
+      end
+
+      ##
+      # Performs a request and returns the number of resources in the collection.
+      #
+      # @raise [RequestFailed]
+      #
+      # @return [Integer] The subordinate resource count
+      def count
+        call_client(:count)
+      end
+
+      ##
+      # Returns true if count is greater than zero, else false.
+      #
+      # @see #count
+      #
+      # @raise [RequestFailed]
+      #
+      # @return [Boolean]
+      def empty?
+        count <= 0
+      end
+
+      ##
+      # Returns a new resource with the given filters added to the query string.
+      #
+      # @see https://github.com/springboard/springboard-retail/blob/master/api/doc/filtering.md Springboard collection API filtering docs
+      #
+      # @param [String, Hash] new_filters Hash or JSON string of new filters
+      #
+      # @return [Resource]
+      def filter(new_filters)
+        new_filters = JSON.parse(new_filters) if new_filters.is_a?(String)
+        if filters = query['_filter']
+          filters = JSON.parse(filters)
+          filters = [filters] unless filters.is_a?(Array)
+          filters.push(new_filters)
+        else
+          filters = new_filters
+        end
+        query('_filter' => filters.to_json)
+      end
+
+      ##
+      # Returns a new resource with the given sorts added to the query string.
+      #
+      # @example
+      #   resource.sort('id,desc', 'name', 'custom@category,desc', :description)
+      #
+      # @param [#to_s] sorts One or more sort strings
+      #
+      # @return [Resource]
+      def sort(*sorts)
+        query('sort' => sorts)
+      end
+
+      ##
+      # Performs a request to get the first result of the first page of the 
+      # collection and returns it.
+      #
+      # @raise [RequestFailed]
+      #
+      # @return [Body] The first entry in the response :results array
+      def first
+        response = query(:per_page => 1, :page => 1).get!
+        response[:results].first
+      end
+
+      ##
+      # Performs repeated GET requests to the resource and yields results to
+      # the given block as long as the response includes more results.
+      #
+      # @raise [RequestFailed]
+      def while_results(&block)
+        loop do
+          results = get![:results]
+          break if results.nil? || results.empty?
+          results.each(&block)
+        end
+      end
+    end
+  end
+end

data/lib/springboard/client/errors.rb

@@ -0,0 +1,17 @@
+module Springboard
+  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/springboard/client/resource.rb

@@ -0,0 +1,205 @@
+require 'springboard/client/collection'
+
+module Springboard
+  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 Springboard Client.
+      #
+      # @return [Client]
+      attr_reader :client
+
+      ##
+      # @param [Springboard::Client] client
+      # @param [Addressable::URI, #to_s] uri
+      def initialize(client, uri)
+        @client = client
+        @uri = URI.join('/', uri.to_s)
+      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
+
+      ##
+      # 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/springboard/client/response.rb

@@ -0,0 +1,85 @@
+module Springboard
+  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 Patron::Response.
+      #
+      # @see http://patron.rubyforge.org/Patron/Response.html Patron::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/springboard/client/uri_ext.rb

@@ -0,0 +1,51 @@
+module Springboard
+  class Client
+    ##
+    # Extensions to the Addressable::URI class.
+    module URIExt
+      ##
+      # 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.
+      def subpath(subpath)
+        uri = dup
+        uri.path = "#{path}/" unless path.end_with?('/')
+        uri.join subpath.to_s.gsub(/^\//, '')
+      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)
+        self.springboard_query_values = (self.query_values || {}).merge(normalize_query_hash(values))
+      end
+
+      private
+
+      def springboard_query_values=(values)
+        retval = self.query_values = normalize_query_hash(values)
+        # Hack to strip digits from Addressable::URI's subscript notation
+        self.query = self.query.gsub(/\[\d+\]=/, '[]=')
+        retval
+      end
+
+      def normalize_query_hash(hash)
+        hash.inject({}) do |copy, (k, v)|
+          copy[k.to_s] = case v
+            when Hash then normalize_query_hash(v)
+            when true, false then v.to_s
+            else v end
+          copy
+        end
+      end
+    end
+  end
+end
+
+##
+# We include Springboard::Client::URIExt into Addressable::URI because its design
+# doesn't support subclassing.
+#
+# @see http://addressable.rubyforge.org/api/Addressable/URI.html Addressable::URI docs
+class Addressable::URI
+  include Springboard::Client::URIExt
+end