rafter-fulfillment 1.0.0

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/fulfillment/client.rb

@@ -0,0 +1,50 @@
+require 'cgi'
+
+module Fulfillment
+  class Client
+
+    attr_accessor :verbose, :logger
+    attr_reader :api_key, :host, :base_uri, :scheme
+
+    DEFAULT_TIMEOUT = 10
+
+    def initialize(options = {})
+      client_options = HashWithIndifferentAccess.new(options)
+      @api_key = client_options[:api_key].nil? ? (raise ArgumentError.new(":api_key is a required argument")) : client_options[:api_key]
+      @host = client_options[:host].nil? ? (raise ArgumentError.new(":host is a required argument")) : client_options[:host]
+      @scheme = client_options[:scheme] || "https"
+      @base_uri = @scheme + "://" + @host
+      @verbose = client_options[:verbose] || false
+      @logger = client_options[:logger] || nil
+      @timeout = client_options[:timeout] || DEFAULT_TIMEOUT
+    end
+
+    def configure_http(http)
+      http.headers["X-API-KEY"] = @api_key
+      http.headers["Accept"] = Fulfillment::API_VERSION
+      http.headers["Content-Type"] = "application/json"
+      if scheme == "https"
+        http.use_ssl = Curl::CURL_USESSL_ALL
+        http.ssl_verify_peer = false
+      end
+      http.verbose = @verbose
+      unless @logger.nil?
+        http.on_debug { |type,data| @logger.info "Fulfillment Client #{data}" }
+      end
+      http.timeout = @timeout
+    end
+    
+    def build_auth_url(resource_path)
+      @base_uri + resource_path
+    end
+
+    def add_query_parameter(curl, key, value)
+      current_url = curl.url
+      curl.url = current_url + (current_url.match(/\?/) ? "&" : "?") + "#{CGI::escape key.to_s}=#{CGI::escape value.to_s}"
+    end
+    
+    def set_request_page(curl, page_num)
+      add_query_parameter(curl, "page", page_num)
+    end
+  end
+end

data/lib/fulfillment/client_exception.rb

@@ -0,0 +1,5 @@
+module Fulfillment
+  class ClientException < StandardError
+
+  end
+end

data/lib/fulfillment/creation_exception.rb

@@ -0,0 +1,5 @@
+module Fulfillment
+  class CreationException < ClientException
+
+  end
+end

data/lib/fulfillment/model_base.rb

@@ -0,0 +1,27 @@
+module Fulfillment
+  class ModelBase
+
+    protected
+
+    def make_getter_methods(data_hash)
+      eigenclass = class << self; self; end
+
+      data_hash.each do |key, value|
+        instance_variable_set "@#{key}", value
+         eigenclass.send(:define_method, key) do
+            instance_variable_get "@#{key}"
+          end
+      end
+    end
+
+    def make_setter_methods(data_hash)
+      eigenclass = class << self; self; end
+
+      data_hash.each do |key, value|
+        eigenclass.send(:define_method, "@#{key}=") do |new_value|
+          instance_variable_set "@#{k}", new_value
+        end
+      end
+    end
+  end
+end

data/lib/fulfillment/order.rb

@@ -0,0 +1,169 @@
+module Fulfillment
+  class Order < ModelBase
+
+    REJECT_CODE_BAD_ORDER_INFO = 1
+    REJECT_CODE_GENERIC = 2
+    REJECT_CODE_OUT_OF_STOCK = 3
+    REJECT_CODES = [REJECT_CODE_BAD_ORDER_INFO, REJECT_CODE_GENERIC, REJECT_CODE_OUT_OF_STOCK]
+
+    attr_accessor :client
+
+    def initialize(client, data)
+      @client = client
+      make_getter_methods(data)
+    end
+
+    def order_items(first_page_num = 1)
+      Fulfillment::OrderItem.list(self.client, self.public_id, first_page_num)
+    end
+    
+    def process
+      Fulfillment::Order.processing_transition(self.client, self.public_id)
+    end
+
+    def processed
+      Fulfillment::Order.processed_transition(self.client, self.public_id)
+    end
+
+    def shipping
+      Fulfillment::Order.shipping_transition(self.client, self.public_id)
+    end
+
+    def shipped
+      Fulfillment::Order.shipped_transition(self.client, self.public_id)
+    end
+    
+    def reject(rejected_code)
+      Fulfillment::Order.reject(self.client, self.public_id, rejected_code)
+    end
+    
+    def create_shipment(shipment_hash)
+      Fulfillment::Shipment.create(self.client, self.public_id, shipment_hash)
+    end
+    
+    def order_shipments
+      Fulfillment::Order.order_shipments(self.client, self.public_id)
+    end
+
+    class << self
+      def order_shipments(client, public_id, first_page_num = 1)
+        Fulfillment::PagedResult.construct(first_page_num) do |page_num|
+          curl = Curl::Easy.http_get(client.build_auth_url("/orders/#{public_id}/shipments")) do |curl|
+            client.configure_http(curl)
+            client.set_request_page(curl, page_num)
+          end
+
+          raise Fulfillment::ClientException.new("Could not load index of shipments for #{public_id}: \n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+          shipment_hashes = JSON.parse(curl.body_str)
+          result = shipment_hashes.map { |sh| Fulfillment::Shipment.new(client, sh) }
+
+          Fulfillment::PagingEnvelope.envelop(curl, result)
+        end
+      end
+      
+      def processing_transition(client, public_id)
+        curl = Curl::Easy.http_put(client.build_auth_url("/orders/#{public_id}/process"), {}) do |curl|
+          client.configure_http(curl)
+        end
+
+        raise Fulfillment::CreationException.new("Could not complete processing transition for #{public_id}:\n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+        new(client, JSON.parse(curl.body_str))
+      end
+      
+      def processed_transition(client, public_id)
+        curl = Curl::Easy.http_put(client.build_auth_url("/orders/#{public_id}/processed"), {}) do |curl|
+          client.configure_http(curl)
+        end
+
+        raise Fulfillment::CreationException.new("Could not complete processed transition for #{public_id}:\n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+        new(client, JSON.parse(curl.body_str))
+      end      
+      
+      def shipping_transition(client, public_id)
+        curl = Curl::Easy.http_put(client.build_auth_url("/orders/#{public_id}/shipping"), {}.to_json) do |curl|
+          client.configure_http(curl)
+        end
+
+        raise Fulfillment::CreationException.new("Could not create shipped transition for #{public_id}:\n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+        new(client, JSON.parse(curl.body_str))
+      end
+      
+      def shipped_transition(client, public_id)
+        curl = Curl::Easy.http_put(client.build_auth_url("/orders/#{public_id}/shipped"), {}.to_json) do |curl|
+          client.configure_http(curl)
+        end
+
+        raise Fulfillment::CreationException.new("Could not create shipped transition for #{public_id}:\n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+        new(client, JSON.parse(curl.body_str))
+      end
+
+      ##
+      # Reject the given FulfillmentOrder based on the public ID. The client must be the named
+      # FulfillmentProvider in order for the "rejection" to be successful.
+      def reject(client, public_id, rejected_code)
+        raise ArgumentError.new("Invalid Reject Code. The following are valid reject codes #{REJECT_CODES.join(",")}") unless REJECT_CODES.include?(rejected_code)
+        error_payload = {"rejected_code" => rejected_code}
+
+        curl = Curl::Easy.http_put(client.build_auth_url("/orders/#{public_id}/reject"), error_payload.to_json) do |curl|
+          client.configure_http(curl)
+        end
+
+        raise Fulfillment::CreationException.new("Could not reject order for #{public_id}:\n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+        new(client, JSON.parse(curl.body_str))
+      end
+
+      def show(client, public_id)
+        curl = Curl::Easy.http_get(client.build_auth_url("/orders/#{public_id}")) do |curl|
+          client.configure_http(curl)
+        end
+
+        raise Fulfillment::ClientException.new("Could not get Order #{public_id}:\n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+        new(client, JSON.parse(curl.body_str))
+      end
+
+      # return a collection of orders for fulfiller in ready status
+      def ready(client, first_page_num = 1)
+        Fulfillment::PagedResult.construct(first_page_num) do |page_num|
+          curl = Curl::Easy.new(client.build_auth_url("/orders/ready")) do |curl|
+            client.configure_http(curl)
+            client.set_request_page(curl, page_num)
+          end
+
+          curl.perform
+          ready_order_hashes = JSON.parse(curl.body_str)
+          result = ready_order_hashes.map { |roh| new(client, roh) }
+
+          Fulfillment::PagingEnvelope.envelop(curl, result)
+        end
+      end
+
+      def search(client, search_options = {})
+        first_page_num = 1
+        Fulfillment::PagedResult.construct(first_page_num) do |page_num|
+          curl = Curl::Easy.http_get(client.build_auth_url("/orders/search")) do |curl|
+            client.configure_http(curl)
+            client.set_request_page(curl, page_num)
+            search_options.each { |k, v| client.add_query_parameter(curl, k, v) }
+            curl
+          end
+
+          raise Fulfillment::SearchException.new("Could not search orders with search options #{search_options}:\n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+          search_result_order_array = JSON.parse(curl.body_str)
+          orders = []
+          search_result_order_array.each { |oh| orders << new(client, oh) }
+
+          Fulfillment::PagingEnvelope.envelop(curl, orders)
+        end
+      end
+
+    end
+  end
+end

data/lib/fulfillment/order_item.rb

@@ -0,0 +1,118 @@
+module Fulfillment
+  class OrderItem < ModelBase
+
+    attr_accessor :client, :order_public_id
+
+    GENERIC_REJECTION = 1 # un-categorized rejection reason
+    OUT_OF_STOCK_REJECTION = 2 # fulfillment provider is temporarily out of stock
+    ITEM_NOT_STOCKED_REJECTION = 3 # fulfillment provider does not know about this item at all
+    RESERVE_EXHAUSTED_REJECTION = 4
+    INVALID_QUANTITY_REJECTION = 5
+    REJECT_CODES = [GENERIC_REJECTION, OUT_OF_STOCK_REJECTION,
+                    ITEM_NOT_STOCKED_REJECTION, RESERVE_EXHAUSTED_REJECTION,
+                    INVALID_QUANTITY_REJECTION]
+
+    def initialize(client, data)
+      @client = client
+      make_getter_methods(data)
+    end
+
+    def reject(rejected_code)
+      Fulfillment::OrderItem.reject(self.client, self.order_public_id, self.public_id, rejected_code)
+    end
+
+    def acknowledge(acknowledgements)
+      Fulfillment::OrderItem.acknowledge(self.client, self.order_public_id, self.public_id, acknowledgements)
+    end
+
+    def process
+      Fulfillment::OrderItem.process(self.client, self.order_public_id, self.public_id)
+    end
+
+    class << self
+
+      ##
+      # Acknowledge quantites accepted / rejected of the given FulfillmentOrderItem based on the FulfillmentOrder public ID 
+      # and the FulfillmentOrderItem public ID.
+      # Accepted and Rejected quantities must be present in the acknowledgements hash
+      def acknowledge(client, order_public_id, order_item_public_id, acknowledgements)
+        if acknowledgements["quantity_accepted"].nil? || acknowledgements["quantity_rejected"].nil?
+          raise ArgumentError.new("Accepted and Rejected quantities must be present in the acknowledgements hash.")
+        end
+
+        curl = Curl::Easy.http_put(client.build_auth_url("/orders/#{order_public_id}/items/#{order_item_public_id}/acknowledge"), acknowledgements.to_json) do |curl|
+          client.configure_http(curl)
+        end
+
+        if curl.response_code != 200
+          raise Fulfillment::CreationException.new("Could not acknowledge item #{order_item_public_id} from order #{order_public_id}:\n\n Response Body:\n #{curl.body_str}")
+        end
+
+        new(client, JSON.parse(curl.body_str))
+      end
+
+      ##
+      # Reject the given FulfillmentOrderItem based on the FulfillmentOrder public ID and the FulfillmentOrderItem
+      # public ID. The client must be the named FulfillmentProvider in order for the "rejection" to be successful.
+      def reject(client, order_public_id, order_item_public_id, rejected_code)
+        raise ArgumentError.new("Invalid Reject Code. The following are valid reject codes #{REJECT_CODES.join(",")}") unless REJECT_CODES.include?(rejected_code)
+        error_payload = {"rejected_code" => rejected_code}
+
+        curl = Curl::Easy.http_put(client.build_auth_url("/orders/#{order_public_id}/items/#{order_item_public_id}/reject"), error_payload.to_json) do |curl|
+          client.configure_http(curl)
+        end
+
+        raise Fulfillment::CreationException.new("Could not reject item #{order_item_public_id} from order #{order_public_id}:\n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+        new(client, JSON.parse(curl.body_str))
+      end
+
+      ##
+      # Process a given FulfillmentOrderItem based on the FulfillmentOrder public_id and the FulfillmentOrderItem
+      # public_id. The client must be the named FulfillmentProvider in order for the 'process' to be successful.
+      def process(client, order_public_id, order_item_public_id)
+        curl = Curl::Easy.http_put(client.build_auth_url("/orders/#{order_public_id}/items/#{order_item_public_id}/process"), {}) do |curl|
+          client.configure_http(curl)
+        end
+
+        raise Fulfillment::CreationException.new("Could not process item #{order_item_public_id} from order #{order_public_id}:\n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+        new(client, JSON.parse(curl.body_str))
+      end
+
+      def list(client, order_public_id, first_page_num = 1)
+        Fulfillment::PagedResult.construct(first_page_num) do |page_num|
+          curl = Curl::Easy.http_get(client.build_auth_url("/orders/#{order_public_id}/items")) do |curl|
+            client.configure_http(curl)
+            client.set_request_page(curl, page_num)
+          end
+          
+          raise Fulfillment::ClientException.new("Could not load index of items for order #{order_public_id}: \n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+          
+          order_item_result_array = JSON.parse(curl.body_str)
+          order_items = []
+          order_item_result_array.each do |ira| 
+            order_item = new(client, ira)
+            order_item.order_public_id = order_public_id
+            order_items << order_item
+          end
+
+          Fulfillment::PagingEnvelope.envelop(curl, order_items)
+        end
+      end
+      
+      def show(client, order_public_id, order_item_public_id)
+        curl = Curl::Easy.http_get(client.build_auth_url("/orders/#{order_public_id}/items/#{order_item_public_id}")) do |curl|
+          client.configure_http(curl)
+        end
+
+        raise Fulfillment::ClientException.new("Could not get order item #{order_item_public_id} for order #{order_public_id}:\n\n Response Body:\n #{curl.body_str}") unless curl.response_code == 200
+
+        order_item = new(client, JSON.parse(curl.body_str))
+        order_item.order_public_id = order_public_id
+        order_item
+      end
+          
+    end
+  end
+end

data/lib/fulfillment/paged_result.rb

@@ -0,0 +1,45 @@
+module Fulfillment
+  class PagedResult
+    include Enumerable
+
+    attr_reader :first_page_num
+
+    # Create a
+
+    # *first_page_number* is the starting page for the associated API call.
+    # *api_caller_proc* is a Proc that returns a hash (of the type returned
+    #     by Exchange::PagingEnvelope.envelope).  Calling the proc and passing
+    #     it a page_number should return an enveloped API call result.
+    def initialize(first_page_num, api_caller_proc)
+      @first_page_num = first_page_num
+      @api_caller_proc = api_caller_proc
+    end
+
+    def pages
+      entries
+    end
+
+    def results
+      pages.flatten
+    end
+
+    def each
+      page_num = @first_page_num
+      enveloped_page = @api_caller_proc.call(page_num)
+      yield enveloped_page[:data]
+      while (page_num < enveloped_page[:total_pages])
+        page_num += 1
+        enveloped_page = @api_caller_proc.call(page_num)
+        yield enveloped_page[:data]
+      end
+    end
+
+    class << self
+
+      # Alternative constructor that takes a block rather than a Proc instance
+      def construct(first_page_num, &api_caller_proc)
+        new(first_page_num, api_caller_proc)
+      end
+    end
+  end
+end

data/lib/fulfillment/paging_envelope.rb

@@ -0,0 +1,36 @@
+module Fulfillment
+  module PagingEnvelope
+    class << self
+
+      # Returns a hash like {per_page:100, total_pages:5, data: data}
+      def envelop(curl, data)
+        per_page, total_pages = get_pages_from_curl(curl)
+        {per_page: per_page, total_pages: total_pages, data: data}
+      end
+
+      private
+
+      def get_paging_json_from_response_header(response_header)
+        if response_header.is_a? String
+          get_paging_json_from_response_header(response_header.split)
+        elsif response_header.count == 0
+          nil
+        elsif response_header[0].upcase == "X-API-PAGINATION:"
+          response_header[1]
+        else
+          get_paging_json_from_response_header(response_header[1..-1])
+        end
+      end
+
+      def get_pages_from_curl(curl_response)
+        response_header = curl_response.header_str
+        if (paging_json = get_paging_json_from_response_header(response_header))
+          paging_hash = JSON.parse(paging_json)
+          [paging_hash["per_page"], paging_hash["total_pages"]]
+        else
+          [nil, nil]
+        end
+      end
+    end
+  end
+end