shipvine 0.1.0

data/lib/shipvine.rb

@@ -0,0 +1,22 @@
+require "shipvine/version"
+
+require 'httparty'
+require 'gyoku'
+require 'nori'
+
+require 'shipvine/error'
+require 'shipvine/client'
+require 'shipvine/base'
+require 'shipvine/fulfillment_request'
+require 'shipvine/inbound_shipment'
+require 'shipvine/outbound_shipment'
+require 'shipvine/bill_of_lading'
+require 'shipvine/item'
+require 'shipvine/item_group'
+require 'shipvine/deep_compact'
+
+module Shipvine
+  class << self
+    attr_accessor :api_key, :merchant_code, :validate_xml, :testmode
+  end
+end

data/lib/shipvine/base.rb

@@ -0,0 +1,69 @@
+module Shipvine
+  class Base
+    WAREHOUSE_XSD_FILE = File.expand_path('../../../data/WarehouseFS-1.0.xsd', __FILE__)
+
+    def self.client
+      @client ||= Shipvine::Client.new
+    end
+
+    def self.xml_to_hash(raw_xml)
+      Nori.new(:convert_tags_to => lambda { |tag| tag.snakecase.to_sym })
+        .parse(raw_xml)
+    end
+
+    protected
+
+      def client
+        self.class.client
+      end
+
+      def add_xml_sequence(hash, order_array)
+        hash[:order!] = order_array.select { |field| hash.keys.include?(field) }
+      end
+
+      def add_sequence_annotations(root_hash)
+        puts "ShipVine: add_sequence_annotations not defined for #{self.class}"
+      end
+
+      def request_body(resource_name, attributes_hash)
+        sanitized_hash = build_sanitized_hash(resource_name, attributes_hash)
+
+        add_sequence_annotations(sanitized_hash[resource_name])
+
+        request_xml = Gyoku.xml(sanitized_hash, {
+          :key_converter => :camelcase
+        })
+
+        if Shipvine.validate_xml.nil? || Shipvine.validate_xml
+          validate_xml!(request_xml)
+        end
+
+        request_xml
+      end
+
+      def build_sanitized_hash(resource_name, hash)
+        # ShipVine doesn't accept `xsi:nil=true` attributes; these must be stripped
+        # before performing hash => XML conversion
+        sanitized = hash.deep_compact!
+
+        {
+          resource_name => {
+            :@xmlns => 'urn:WarehouseFS-1.0',
+            :merchant_code => Shipvine.merchant_code
+          }.merge(sanitized)
+        }
+      end
+
+      def validate_xml!(xml)
+        xsd = Nokogiri::XML::Schema(File.read(WAREHOUSE_XSD_FILE))
+        doc = Nokogiri::XML(xml)
+
+        errors = xsd.validate(doc)
+
+        if !errors.empty?
+          puts xml
+          raise "Error validating XML: #{errors.join("\n")}"
+        end
+      end
+  end
+end

data/lib/shipvine/bill_of_lading.rb

@@ -0,0 +1,21 @@
+module Shipvine
+  class BillOfLading < Base
+
+    attr_accessor :formatted, :numeric
+
+    def self.generate
+      response = self.client.request(
+        :post,
+        '/bol-numbers/' + Shipvine.merchant_code,
+        ''
+      )
+
+      lading = self.new
+      lading.formatted = response["BillOfLadingNumber"]["Formatted"]
+      lading.numeric = response["BillOfLadingNumber"]["Numeric"]
+
+      lading
+    end
+
+  end
+end

data/lib/shipvine/client.rb

@@ -0,0 +1,78 @@
+module Shipvine
+  class Client
+    include HTTParty
+    base_uri 'https://api.warehousefs.com/public/v1/'
+
+    def initialize(opts = {})
+      @options = opts
+    end
+
+    def request(method, resource, params = {}, exclude_merchant_code: false)
+      options = default_options.deep_merge(@options)
+
+      options = if method == :get
+        options.merge(query:
+          sanitize_query_parameters(params, exclude_merchant_code: exclude_merchant_code)
+        )
+      else
+        # TODO a sanitization method is needed here
+        options.merge(body: params)
+      end
+
+      response = self.class.send(method, resource, options)
+
+      # NOTE response will be nil if the body of the response is nil
+
+      if response.code != 200
+        # TODO response.response.message == 'Unauthorized' in the case of 401
+        #      possibly try to sniff out more descriptive error information
+
+        fail Shipvine::Error.new(response), "#{response.code} #{response.body}"
+      else
+        response
+      end
+    end
+
+    protected
+
+      def sanitize_query_parameters(params, exclude_merchant_code: false)
+        params = params.dup
+
+        # TODO dynamic for input params hyphen/kebab case conversion
+        # TODO stop hard coding shipvine parameter possibilities here
+
+        params.each do |k, v|
+          # force iso8601 on date/time
+          if %w(created-since changed-since).include?(k) && [ DateTime, Date, Time ].include?(v.class)
+            params[k] = v.iso8601
+          end
+        end
+
+        # NOTE some endpoints include the merchant code in the URL
+
+        if exclude_merchant_code
+          params
+        else
+          { 'merchant-code' => Shipvine.merchant_code }.merge(params)
+        end
+      end
+
+      def default_options
+        opts = {
+          headers: {
+            'X-Api-Key' => Shipvine.api_key
+          }
+        }
+
+        if Shipvine.testmode
+          opts[:headers]['X-Api-Test'] = 'true'
+        end
+
+        opts
+      end
+
+      def sanitize_body_parameters
+        # ruby has to xml
+      end
+  end
+end

data/lib/shipvine/deep_compact.rb

@@ -0,0 +1,23 @@
+# https://github.com/infochimps-labs/gorillib/blob/cd88bed1cba29c31f27dcce90bddbcbfbca33487/lib/gorillib/array/deep_compact.rb
+
+class Hash
+  def deep_compact!
+    each_pair do |key, val|
+      val.deep_compact! if val.respond_to?(:deep_compact!)
+      delete(key) if val.blank?
+    end
+    self
+  end
+end
+
+class Array
+  #
+  # deep_compact! removes all 'blank?' elements in the array in place, recursively
+  #
+  def deep_compact!
+    self.map! do |val|
+      val.deep_compact! if val.respond_to?(:deep_compact!)
+      val unless val.blank?
+    end.compact!
+  end
+end

data/lib/shipvine/error.rb

@@ -0,0 +1,12 @@
+module Shipvine
+  class Error < StandardError
+    attr_reader :code, :shipvine_message
+
+    def initialize(response = nil)
+      if response.present?
+        @code = response.code
+        @shipvine_message = response.parsed_response["Errors"]["Error"]["Message"]
+      end
+    end
+  end
+end

data/lib/shipvine/fulfillment_request.rb

@@ -0,0 +1,243 @@
+module Shipvine
+  class FulfillmentRequest < Base
+    STATIC_REQUEST_ELEMENTS = {
+      currency: 'USD',
+      discount: {
+        amount: 0.0,
+        currency: 'USD'
+      },
+      tax: {
+        amount: 0.0,
+        currency: 'USD'
+      },
+      shipping: {
+        amount: 0.0,
+        currency: 'USD'
+      }
+    }.freeze
+
+    # TODO split classes into FulfillmentRequestSubmission and FulfillmentRequest?
+
+    def self.get_shipvine_identifier(merchant_identifier)
+      request = self.client.request(
+        :get,
+        '/fulfillment-requests',
+        {
+          "merchant-identifier" => merchant_identifier
+        }
+      )
+
+      request["FulfillmentRequests"]["FulfillmentRequest"]["ShipvineIdentifier"]
+    rescue Shipvine::Error => e
+      # NOTE SV will return a 404, or other non-200 response if the fulfillment does not exist
+      nil
+    end
+
+    def self.get(shipvine_identifier)
+      request = self.client.request(
+        :get,
+        '/fulfillment-requests/' + shipvine_identifier
+      )
+
+      self.new(self.xml_to_hash(request.body))
+    end
+
+    attr_reader :attributes
+
+    def initialize(attributes)
+      @attributes = attributes
+    end
+
+    def metadata
+      metadata_entries = self.attributes.dig(:fulfillment_request, :metadata, :metadata)
+
+      if metadata_entries.nil? || metadata_entries.empty?
+        return {}
+      end
+
+      # TODO cache the resulting hash here
+
+      metadata_entries = Array.wrap(metadata_entries)
+
+      metadata_entries.inject({}) do |h, sv_metadata_entry|
+        h[sv_metadata_entry[:name]] = sv_metadata_entry[:value]
+        h
+      end
+    end
+
+    def create
+      translated_payload = @attributes.deep_dup
+
+      preprocess_lines(translated_payload)
+      preprocess_address(translated_payload)
+      preprocess_metadata(translated_payload)
+      add_static_elements(translated_payload)
+
+      client.request(
+        :post,
+        '/fulfillment-request-submissions',
+        request_body('FulfillmentRequestSubmission', translated_payload)
+      )
+    end
+
+    protected
+
+      def add_static_elements(order_hash)
+        order_hash.merge!(STATIC_REQUEST_ELEMENTS)
+      end
+
+      def preprocess_metadata(order_hash)
+        metadata = order_hash.delete(:metadata)
+
+        if metadata
+          order_hash[:request_metadata] = {
+            :metadata => metadata.map do |k, v|
+              {
+                name: k,
+                value: v
+              }
+            end
+          }
+        end
+      end
+
+      def preprocess_lines(order_hash)
+        items = order_hash.delete(:lines)
+
+        order_hash[:lines] = {
+          :line => items.map do |item|
+            h = {
+              item: {
+                # TODO support other item keys, `sku`, `id`, etc
+                merchant_identifier: item[:product_id]
+              },
+              quantity: item[:quantity],
+              unit_price: {
+                amount: 0.0,
+                currency: 'USD'
+              }
+            }
+
+            if item[:stored_value]
+              h[:item][:stored_value] = {
+                amount: item[:stored_value],
+                currency: 'USD'
+              }
+            end
+
+            if item[:gift_box]
+              h[:item][:gift_box] = true
+            end
+
+            if item[:modifications]
+              h[:item][:modifications] = {
+                modification: item[:modifications]
+              }
+            end
+
+            h
+          end
+        }
+
+        order_hash
+      end
+
+      def preprocess_address(order_hash)
+        order_hash[:address][:@type] = "Shipping"
+        order_hash[:address][:country] ||= 'US'
+
+        address1 = order_hash[:address].delete(:address1)
+        address2 = order_hash[:address].delete(:address2)
+
+        order_hash[:address][:street_lines] = {
+          :street_line => [
+            address1,
+            address2
+          ]
+        }
+
+        order_hash[:address][:personal_name] = {
+          first: order_hash.delete(:first_name),
+          last: order_hash.delete(:last_name)
+        }
+
+        # shipvine requires first and last; pull from company field if not defined
+        if order_hash[:address][:personal_name][:first].blank? || order_hash[:address][:personal_name][:last].blank?
+          if order_hash[:address][:company].nil? || order_hash[:address][:company].empty?
+            fail "both name and company fields are empty, cannot create fulfillment"
+          end
+
+          first_name, last_name = order_hash[:address][:company].split(' ', 2)
+
+          # NOTE first and last name are always required in ShipVine
+          #      ensure that *some* value is always set
+
+          if last_name.nil?
+            last_name = first_name
+          end
+
+          if first_name.nil?
+            first_name = last_name
+          end
+
+          order_hash[:address][:personal_name][:first] ||= first_name
+          order_hash[:address][:personal_name][:last] ||= last_name
+        end
+
+        order_hash
+      end
+
+      def add_sequence_annotations(hash)
+        add_xml_sequence(hash, %i(
+          merchant_code
+          merchant_identifier
+          customer_identifier
+          bill_of_lading_number
+          currency
+          email_address
+          address
+          lines
+          requested_documents
+          merchant_return_profile
+          ucc_label_template
+          packing_slip_template
+          shipping_method
+          shipping_charges_payer
+          return_label
+          discount
+          tax
+          shipping
+          request_metadata
+        ))
+
+        add_xml_sequence(hash[:address], %i(
+          country
+          personal_name
+          company
+          street_lines
+          city_or_town
+          state_or_province
+          postal_code
+          phone
+        ))
+
+        hash[:lines][:line].each do |line|
+          add_xml_sequence(line, %i(
+            item
+            quantity
+            unit_price
+          ))
+
+          add_xml_sequence(line[:item], %i(
+            merchant_identifier
+            modifications
+            stored_value
+            gift_box
+          ))
+        end
+
+        # TODO specify first and last order under `personal_name`
+      end
+
+  end
+end