ship_compliant 0.1.0

data/lib/ship_compliant.rb

@@ -0,0 +1,62 @@
+require 'savon'
+require 'active_support/all'
+
+require "ship_compliant/version"
+require "ship_compliant/configuration"
+require "ship_compliant/client"
+require "ship_compliant/base_result"
+require "ship_compliant/error_result"
+
+require "ship_compliant/address"
+require "ship_compliant/address/suggested_address"
+
+require "ship_compliant/shipment"
+require "ship_compliant/package"
+require "ship_compliant/channel_details"
+
+# SEARCH SALES ORDERS
+require "ship_compliant/order_search"
+require "ship_compliant/search_sales_orders"
+require "ship_compliant/search_sales_orders_result"
+require "ship_compliant/search_sales_order_summary"
+
+require "ship_compliant/get_sales_order_extended"
+require "ship_compliant/get_sales_order_extended_result"
+
+# VOID SALES ORDER
+require "ship_compliant/void_sales_order"
+require "ship_compliant/void_sales_order_result"
+
+# ADD UPDATE PRODUCT
+require "ship_compliant/product_attributes"
+require "ship_compliant/add_update_product"
+require "ship_compliant/add_update_product_result"
+
+# ADD UPDATE BRAND
+require "ship_compliant/add_update_brand"
+require "ship_compliant/add_update_brand_result"
+
+# SALES TAX
+require "ship_compliant/shipment_sales_tax_rate"
+require "ship_compliant/sales_tax_rate"
+require "ship_compliant/product_sales_tax_rate"
+require "ship_compliant/freight_sales_tax_rate"
+
+# CHECK COMPLIANCE OF SALES ORDER WITH ADDRESS VALIDATION
+require "ship_compliant/check_compliance"
+require "ship_compliant/check_compliance_result"
+
+require "ship_compliant/shipment_compliance"
+require "ship_compliant/compliance_rule"
+
+require "ship_compliant/commit_sales_order"
+require "ship_compliant/commit_sales_order_result"
+
+require "ship_compliant/inventory_product"
+
+require "ship_compliant/get_inventory_details"
+require "ship_compliant/get_inventory_details_result"
+
+module ShipCompliant
+  # Your code goes here...
+end

data/lib/ship_compliant/add_update_brand.rb

@@ -0,0 +1,50 @@
+module ShipCompliant
+  # == ShipCompliant::AddUpdateBrand
+  #
+  # Checks to see if a brand with the same key already exists. If one does not
+  # exist, it will add the brand with the specified name. If a brand exists
+  # with the same brand key then the brand name will be updated.
+  #
+  # Use this method to add a new brand or update an existing brand in the
+  # system. A brand must be defined before adding products.
+  #
+  #   ShipCompliant::AddUpdateBrand.brand({
+  #     key: 'DENSNW',
+  #     name: 'Denver Snow',
+  #     
+  #     this_brand_is_bottled_by_a_third_party: false,
+  #     this_brand_is_produced_by_a_third_party: false,
+  #     this_brand_operates_under_a_trade_name: false,
+  #     this_brand_was_acquired_from_a_third_party: false
+  #   })
+  class AddUpdateBrand
+
+    # Adds or updates a brand depending on +:update_mode+.
+    #
+    # +brand+ parameter must be a Hash.
+    #
+    # === Options
+    #
+    # You can specify the update mode by passing a hash as the second argument.
+    # The default is +ErrorOnExisting+.
+    #
+    # Available options are.
+    #
+    # * UpdateExisting - Existing brand information is updated.
+    # * IgnoreExisting - Pre-existing information is not updated.
+    # * ErrorOnExisting - An error message is returned if the brand already exists.
+    #
+    #     ShipCompliant::AddUpdateBrand.product({
+    #       # brand attributes
+    #     }, update_mode: 'UpdateExisting')
+    def self.brand(brand, options = {})
+      result = ShipCompliant.client.call(:add_update_brand, {
+        'Brand' => brand.deep_transform_keys { |key| key.to_s.camelize },
+        'UpdateMode' => options.fetch(:update_mode, 'ErrorOnExisting')
+      })
+
+      AddUpdateBrandResult.new(result)
+    end
+
+  end
+end

data/lib/ship_compliant/add_update_brand_result.rb

@@ -0,0 +1,6 @@
+module ShipCompliant
+  # == ShipCompliant::AddUpdateBrandResult
+  class AddUpdateBrandResult < Struct.new(:response)
+    include BaseResult
+  end
+end

data/lib/ship_compliant/add_update_product.rb

@@ -0,0 +1,66 @@
+module ShipCompliant
+  # == ShipCompliant::AddUpdateProduct
+  #
+  # This method checks to see if a product with the same product key and brand
+  # key already exists.
+  #
+  # If one does not exist, it will add the product with the specified
+  # information.
+  #
+  # If a product exists with the same product key and brand key, but is not
+  # referenced by any shipments, the product will be updated with the specified
+  # information.
+  #
+  # If a product exists with the same product key and brand key, and is
+  # referenced by one or more shipments, the product will not be updated.
+  #
+  #   result = ShipCompliant::AddUpdateProduct.product({
+  #     # product attributes
+  #   }, update_mode: 'IgnoreExisting')
+  #
+  #   if result.success?
+  #     puts "Product added successfully.
+  #   else
+  #     result.errors.each do |error|
+  #       puts error.message
+  #     end
+  #   end
+  class AddUpdateProduct
+
+    # Adds or updates product depending on +:update_mode+.
+    #
+    # +product+ parameter must be a Hash. The keys must be related to the the
+    # keys located in ShipCompliant::ProductAttributes.
+    #
+    # === Options
+    #
+    # You can specify the update mode by passing a Hash as the second argument.
+    # The default is +ErrorOnExisting+.
+    #
+    # Available options are.
+    #
+    # * UpdateExisting - Existing product information is updated.
+    # * IgnoreExisting - Pre-existing information is not updated.
+    # * ErrorOnExisting - An error message is returned if the product already exists.
+    #
+    #     ShipCompliant::AddUpdateProduct.product({
+    #       # product attributes
+    #     }, update_mode: 'UpdateExisting')
+    def self.product(product, options = {})
+      details = {
+        'Product' => ProductAttributes.new(product).to_h,
+        'UpdateMode' => options.fetch(:update_mode, 'ErrorOnExisting')
+      }
+
+      result = add_update_product(details)
+      AddUpdateProductResult.new(result)
+    end
+
+    private
+
+    def self.add_update_product(request)
+      ShipCompliant.client.call(:add_update_product, request)
+    end
+
+  end
+end

data/lib/ship_compliant/add_update_product_result.rb

@@ -0,0 +1,6 @@
+module ShipCompliant
+  # == ShipCompliant::AddUpdateProductResult
+  class AddUpdateProductResult < Struct.new(:response)
+    include BaseResult
+  end
+end

data/lib/ship_compliant/address.rb

@@ -0,0 +1,87 @@
+module ShipCompliant
+  # == ShipCompliant::Address
+  #
+  # This is a value object that wraps an address node. +BillTo+ and +ShipTo+.
+  #
+  #   address = ShipCompliant::Address.new(city: 'Boston', state: 'MA')
+  #   address.city #=> 'Boston'
+  #   address.state #=> 'MA'
+  class Address < Struct.new(:address)
+
+    # Returns the suggested city.
+    def city
+      address[:city]
+    end
+    
+    # Returns the suggested county.
+    def county
+      address[:county]
+    end
+
+    # Returns the suggested state.
+    def state
+      address[:state]
+    end
+
+    # Returns the country.
+    def country
+      address[:country]
+    end
+
+    # Returns the suggested street.
+    def street1
+      address[:street1]
+    end
+
+    # Returns the suggested street line 2.
+    def street2
+      address[:street2]
+    end
+
+    # Returns the suggested zip code.
+    def zip1
+      address[:zip1].to_i
+    end
+
+    # Returns the suggested zip code extension.
+    def zip2
+      return nil if address[:zip2].blank?
+      address[:zip2].to_i
+    end
+
+    # Returns the company.
+    def company
+      address[:company]
+    end
+
+    # Returns the first name.
+    def first_name
+      address[:first_name]
+    end
+
+    # Returns the last name.
+    def last_name
+      address[:last_name]
+    end
+
+    # Returns the phone.
+    def phone
+      address[:phone]
+    end
+
+    # Returns the fax.
+    def fax
+      address[:fax]
+    end
+
+    # Returns the email address.
+    def email
+      address[:email]
+    end
+
+    # Returns the date of birth.
+    def date_of_birth
+      address[:date_of_birth]
+    end
+  end
+end

data/lib/ship_compliant/address/suggested_address.rb

@@ -0,0 +1,37 @@
+module ShipCompliant
+  # == ShipCompliant::SuggestedAddress
+  #
+  # This is a value object that wraps the +SuggestedAddress+ node. It inherits
+  # methods from Address, but it also as methods to access suggested address
+  # details and parts.
+  class SuggestedAddress < Address
+
+    # Returns a Hash of the address location details.
+    #
+    # - +city_abbreviation+
+    # - +congressional_district+
+    # - +county_fips+
+    # - +time_zone+
+    # - +time_zone_code+
+    def details
+      address[:details]
+    end
+
+    # Returns a Hash of the address parts.
+    #
+    # - +company+
+    # - +mail_box_name+
+    # - +mail_box_number+
+    # - +post_direction+
+    # - +pre_direction+
+    # - +street_name+
+    # - +street_number+
+    # - +street_suffix+
+    # - +suite_name+
+    # - +suite_number+
+    def parts
+      address[:parts]
+    end
+
+  end
+end

data/lib/ship_compliant/base_result.rb

@@ -0,0 +1,43 @@
+module ShipCompliant
+  # == ShipCompliant::BaseResult
+  #
+  # This class provides methods to are relevant to every
+  # API request. All requests made through the
+  # ShipCompliant API client include these methods.
+  module BaseResult
+
+    # Returns boolean whether order was successfully voided.
+    #
+    #   puts "SUCCESS" if result.success?
+    def success?
+      response[:response_status] == "Success"
+    end
+
+    # Returns true if order failed to be voided.
+    #
+    #   puts "FAILED" if result.failure?
+    def failure?
+      !success?
+    end
+
+    # An array of +ErrorResult+ items or an empty array if the response was
+    # successful.
+    #
+    #   result.errors.each do |error|
+    #     puts "#{error.message} [#error.key]"
+    #   end
+    def errors
+      return [] if success?
+      @errors ||= Array.wrap(response[:errors]).map do |error|
+        ErrorResult.new(error[:error])
+      end
+    end
+
+    # The number of errors in the response.
+    def errors_count
+      errors.length
+    end
+    alias_method :error_count, :errors_count
+
+  end
+end

data/lib/ship_compliant/channel_details.rb

@@ -0,0 +1,31 @@
+module ShipCompliant
+  # == ShipCompliant::ChannelDetails
+  #
+  # A value object that wraps the +OrderChanelDetails+ node.
+  #
+  #   channel_details = sales_order.channel_details
+  #   puts channel_details.order_channel #=> 'MyOrders'
+  class ChannelDetails < Struct.new(:channel)
+
+    # Returns +OrderChannel+.
+    def order_channel
+      channel[:order_channel]
+    end
+
+    # Returns +AdvertiserKey+.
+    def advertiser_key
+      channel[:advertiser_key]
+    end
+
+    # Returns +AdvertiserName+.
+    def advertiser_name
+      channel[:advertiser_name]
+    end
+
+    # Returns +Meta+.
+    def meta
+      channel[:meta]
+    end
+
+  end
+end

data/lib/ship_compliant/check_compliance.rb

@@ -0,0 +1,41 @@
+module ShipCompliant
+  # == ShipCompliant::CheckCompliance
+  #
+  # The CheckComplianceOfSalesOrderWithAddressValidation API method is used for
+  # real time compliance checks from the order point of entry (eCommerce, POS).  
+  #
+  # The method can do three things in one call:
+  #
+  # - Calculate Sales Tax Due for order and return product level tax rates
+  #   (IncludeSalesTaxRates = true)
+  # - Validate the ShipTo address and get normalized address result
+  # - Check compliance of the order
+  #  
+  # This method takes requires specific order information from the order point
+  # of entry for ShipCompliant to check the order for compliance.  The sales
+  # order will not be committed via this method.  This API call is usually
+  # paired with CommitSalesOrder() to save the sales order to ShipCompliant.
+  #
+  # Look at the following example request: http://git.io/xMNOvw
+  class CheckCompliance
+
+    # Checks the compliance of a sales order from the data specified.
+    #
+    # An example of all the required fields can be seen here: http://git.io/xMNOvw
+    #
+    #   ShipCompliant::CheckCompliance.of_sales_order({
+    #     address_option: {
+    #       ignore_street_level_errors: true,
+    #       reject_if_address_suggested: 'false' # Savon bug? Passes the value as an attribute when a boolean
+    #     },
+    #     include_sales_tax_rates: true,
+    #     # ...
+    #   })
+    def self.of_sales_order(data)
+      camel_cased_keys = data.deep_transform_keys { |key| key.to_s.camelize }
+      result = ShipCompliant.client.call(:check_compliance_of_sales_order_with_address_validation, camel_cased_keys)
+      CheckComplianceResult.new(result)
+    end
+
+  end
+end

data/lib/ship_compliant/check_compliance_result.rb

@@ -0,0 +1,95 @@
+module ShipCompliant
+  # == ShipCompliant::CheckComplianceResult
+  #
+  # CheckComplianceResult wraps the response from the
+  # +CheckComplianceOfSalesOrderWithAddressValidation+ API method.
+  #
+  # It provides methods to access nested objects and easily iterate over taxes
+  # rates for shipments.
+  # 
+  #   compliant_status = ShipCompliant::CheckCompliance.of_sales_order({
+  #     # attributes here
+  #   })
+  #
+  #   compliant_status.compliant? #=> true
+  class CheckComplianceResult < Struct.new(:response)
+    include BaseResult
+
+    # Returns true if all shipments of a SalesOrder are compliant.
+    def compliant?
+      response[:sales_order][:is_compliant] == true
+    end
+
+    # Returns a float of the recommended sales tax due for a SalesOrder.
+    def recommended_tax_due
+      response[:sales_order][:sales_tax_rates][:recommended_sales_tax_due].to_f
+    end
+
+    # Access the tax information for a shipment. Returns an instance of
+    # ShipmentSalesTaxRate.
+    def taxes_for_shipment(shipment_key)
+      shipment = shipment_sales_tax_rates.select { |s| s[:@shipment_key] == shipment_key }.first
+
+      # convert attribute keys to symbols
+      freight = attributes_to_symbols(shipment[:freight_sales_tax_rate])
+
+      # wrap products in ProductSalesTaxRate
+      products = wrap_products(shipment[:product_sales_tax_rates])
+
+      ShipmentSalesTaxRate.new(shipment_key, FreightSalesTaxRate.new(freight), products)
+    end
+
+    # This method returns an Array containing information about each shipment of a
+    # SalesOrder.
+    def shipment_sales_tax_rates
+      Array.wrap(response[:sales_order][:sales_tax_rates][:shipment_sales_tax_rates][:shipment_sales_tax_rate])
+    end
+
+    # Returns an array of the +ShipmentComplianceResponse+ node as a Hash.
+    #
+    #   compliance_result.shipment_compliance_rules.each do |shipment|
+    #     puts "SHIPMENT '#{shipment[:key]}' IS NOT COMPLIANT" unless shipment[:is_compliant]
+    #   end
+    def shipment_compliance_rules
+      Array.wrap(response[:sales_order][:shipments][:shipment_compliance_response])
+    end
+
+    # Finds all the compliance rules for a shipment.
+    # Returns an instance of ShipmentCompliance.
+    #
+    #  shipment_compliance = compliance_result.compliance_rules_for_shipment('SHIPMENT-KEY')
+    #  puts shipment_compliance.compliant? #=> false
+    def compliance_rules_for_shipment(shipment_key)
+      shipment = shipment_compliance_rules.select { |s| s[:key] == shipment_key }.first
+      ShipmentCompliance.new(shipment)
+    end
+
+    # Returns the +AddressValidationResult+.
+    def address_validation_result
+      response[:address_validation_result]
+    end
+
+    # Returns an instance of ShipCompliant::SuggestedAddress.
+    def suggested_address
+      SuggestedAddress.new(response[:suggested_address])
+    end
+
+    private
+    
+    # Nori returns XML attributes as a key beginning with a spiral (@).
+    # This removes the spiral and changes key to a symbol.
+    def attributes_to_symbols(object)
+      object.transform_keys do |key|
+        key.to_s.gsub('@', '').to_sym
+      end
+    end
+
+    # Wraps each +ProductSalesTaxRates+ node with
+    # ShipCompliant::ProductSalesTaxRate
+    def wrap_products(products)
+      Array.wrap(products[:product_sales_tax_rate]).map do |product|
+        ProductSalesTaxRate.new(attributes_to_symbols(product))
+      end
+    end
+  end
+end