ship_compliant 0.1.0

data/lib/ship_compliant/order_search.rb

@@ -0,0 +1,92 @@
+module ShipCompliant
+  # === ShipCompliant::OrderSearch
+  #
+  # Acts as a hash for adding search criteria to the +SearchSalesOrders+
+  # API endpoint. It removes invalid keys when converting to a Hash.
+  #
+  #   query = ShipCompliant::OrderSearch({
+  #     invalid: 'lolz',
+  #     requested_ship_date_max: DateTime.new(2014, 1, 1)
+  #   })
+  #
+  #   query.to_h #=> {
+  #     'RequestedShipDateMax' => DateTime
+  #   }
+  class OrderSearch < Struct.new(:details)
+
+    # == Available Search Methods
+    #
+    # * +channel+
+    # * +compliance_status+
+    # * +external_club_key+
+    # * +external_offer_key+
+    # * +external_sales_order_key_max+
+    # * +external_sales_order_keys+
+    # * +fulfillment_house+
+    # * +fulfillment_status+
+    # * +fulfillment_account+
+    # * +fulfillment_exception_type+
+    # * +license_relationship_type+
+    # * +not_tag+
+    # * +purchase_date_max+
+    # * +purchase_date_min+
+    # * +requested_ship_date_max+
+    # * +requested_ship_date_min+
+    # * +sale_type+
+    # * +sales_order_keys+
+    # * +sales_order_key_min+
+    # * +sales_order_key_max+
+    # * +settlement_batch_number+
+    # * +shipment_status+
+    # * +ship_date_max+
+    # * +ship_date_min+
+    # * +ship_to_state+
+    # * +tag+
+    # * +tracking_existence+
+    KEYS = [
+      :channel,
+      :compliance_status,
+
+      :external_club_key,
+      :external_offer_key,
+      :external_sales_order_key_max,
+      :external_sales_order_keys,
+
+      :fulfillment_house,
+      :fulfillment_status,
+      :fulfillment_account,
+      :fulfillment_exception_type,
+      
+      :license_relationship_type,
+      :not_tag,
+      :purchase_date_max,
+      :purchase_date_min,
+
+      :requested_ship_date_max,
+      :requested_ship_date_min,
+
+      :sale_type,
+      :sales_order_keys,
+      :sales_order_key_min,
+      :sales_order_key_max,
+
+      :settlement_batch_number,
+      :shipment_status,
+      :ship_date_max,
+      :ship_date_min,
+      :ship_to_state,
+
+      :tag,
+      :tracking_existence,
+    ]
+
+    # Converts hash keys to Pascal case and rejects invalid keys.
+    #
+    #   :sales_order_keys #=> 'SalesOrderKeys'
+    def to_h
+      details.reject do |key|
+        !KEYS.include?(key)
+      end.deep_transform_keys { |key| key.to_s.camelize }
+    end
+  end
+end

data/lib/ship_compliant/package.rb

@@ -0,0 +1,13 @@
+module ShipCompliant
+  class Package < Struct.new(:package)
+
+    def tracking_number
+      package[:tracking_number]
+    end
+
+    def tracking_status
+      package[:tracking_status]
+    end
+
+  end
+end

data/lib/ship_compliant/product_attributes.rb

@@ -0,0 +1,98 @@
+module ShipCompliant
+  # === ShipCompliant::ProductAttributes
+  #
+  # Acts as a hash for working with the +AddUpdateProduct+ API endpoint.
+  #
+  #   attributes = ShipCompliant::ProductAttributes({
+  #     bottle_size_ml: 750,
+  #     gtin: 'value',
+  #     product_description: 'It's great!'
+  #   })
+  #
+  #   attributes.to_h #=> {
+  #     'BottleSizeML' => 750,
+  #     'GTIN' => 'value',
+  #     'ProductDescription' => 'It's great!'
+  #   }
+  class ProductAttributes < Struct.new(:details)
+    # == Available Product Attributes
+    #
+    #   * +age+
+    #   * +bottle_size_ml+
+    #   * +brand_key+
+    #   * +default_case+
+    #   * +default_retail_unit_price+
+    #   * +default_retail_case_price+
+    #   * +description+
+    #   * +flavor+
+    #   * +gtin+
+    #   * +label+
+    #   * +percent_alcohol+
+    #   * +product_key+
+    #   * +product_type+
+    #   * +product_description+
+    #   * +nabca+
+    #   * +scc+
+    #   * +upc+
+    #   * +unimerc+
+    #   * +unit_price+
+    #   * +varietal+
+    #   * +vintage+
+    #   * +volume_amount+
+    #   * +volume_unit+
+    KEYS = [
+      :age,
+      :bottle_size_ml,
+      :brand_key,
+
+      :default_case,
+      :default_retail_unit_price,
+      :default_retail_case_price,
+      :description,
+
+      :flavor,
+      :gtin,
+      :label,
+      
+      :percent_alcohol,
+      :product_key,
+      :product_type,
+      :product_description,
+
+      :nabca,
+      :scc,
+      :upc,
+      :unimerc,
+      :unit_price,
+
+      :varietal,
+      :vintage,
+      :volume_amount,
+      :volume_unit
+    ]
+
+    SPECIAL_CASES = {
+      gtin: 'GTIN',
+      nabca: 'NABCA',
+      scc: 'SCC',
+      unimerc: 'UNIMERC',
+      upc: 'UPC',
+      bottle_size_ml: 'BottleSizeML'
+    }
+
+    # Converts hash keys to Pascal case and handles special cases.
+    #
+    #   :bottle_size_ml #=> 'BottleSizeML'
+    def to_h
+      details.deep_transform_keys do |key|
+        # handle special cases
+        pascal_key = key.to_s.camelize
+        if SPECIAL_CASES.has_key?(key)
+          pascal_key = SPECIAL_CASES[key]
+        end
+        
+        pascal_key
+      end
+    end
+  end
+end

data/lib/ship_compliant/product_sales_tax_rate.rb

@@ -0,0 +1,23 @@
+module ShipCompliant
+  # == ShipCompliant::ProductSalesTaxRate
+  #
+  # ProductSalesTaxRate wraps the SalesTaxRate value object. It provides methods
+  # to easily access various attributes about each product.
+  class ProductSalesTaxRate < SalesTaxRate
+
+    # Returns the product's key.
+    #
+    #   product_tax_rate.product_key #=> 'ProductKey123'
+    def product_key
+      sales_tax[:product_key]
+    end
+
+    # Returns the product's brand key.
+    #
+    #   product_tax_rate.brand_key #=> 'BrandKey123'
+    def brand_key
+      sales_tax[:brand_key]
+    end
+
+  end
+end

data/lib/ship_compliant/sales_tax_rate.rb

@@ -0,0 +1,22 @@
+module ShipCompliant
+  # == ShipCompliant::SalesTaxRate
+  #
+  # SalesTaxRate is a value object to store sales tax information for freight
+  # and products.
+  #
+  #   tax_rate = SalesTaxRate.new(sales_tax_due: '123.45')
+  #   puts tax_rate.sales_tax_due #=> 123.45
+  class SalesTaxRate < Struct.new(:sales_tax)
+
+    # Returns the +sales_tax_due+ as a float.
+    def sales_tax_due
+      sales_tax[:sales_tax_due].to_f
+    end
+
+    # Returns the +sales_tax_rate+ as a float.
+    def sales_tax_rate
+      sales_tax[:sales_tax_rate].to_f
+    end
+
+  end
+end

data/lib/ship_compliant/search_sales_order_summary.rb

@@ -0,0 +1,30 @@
+module ShipCompliant
+  # === ShipCompliant::SearchSalesOrderSummary
+  #
+  # Wraps the +SalesOrderSummary+ hash with a simple DSL
+  # to provide easy access to various keys.
+  class SearchSalesOrderSummary < Struct.new(:data)
+
+    # Returns a +DateTime+ from the order +purchase_date+
+    def purchase_date
+      data[:purchase_date]
+    end
+
+    # Returns the +sales_order_key+
+    def order_key
+      data[:sales_order_key]
+    end
+    alias_method :sales_order_key, :order_key
+
+    # Returns the parsed hash from the +ShipmentSummary+ element.
+    #
+    #   {
+    #     compliance: 'ValueHere',
+    #     requested_ship_date: DateTime,
+    #     # etc...
+    #   }
+    def shipment_summary
+      data[:shipments][:shipment_summary]
+    end
+  end
+end

data/lib/ship_compliant/search_sales_orders.rb

@@ -0,0 +1,53 @@
+module ShipCompliant
+  # == ShipCompliant::SearchSalesOrders
+  #
+  # Search orders in the ShipCompliant database on a number of different
+  # criteria such as date ranges, order number range, order list, status, etc...
+  #
+  # Summary details, including tracking numbers, of Sales Orders and
+  # Shipments are returned for the first 100 orders that meet the search criteria.
+  #
+  # Use this method to get tracking numbers for a collection of orders,
+  # check shipping status, check compliance status, or check fulfillment status.
+  #
+  # Results are paged, and only the first 100 results are returned with this method.
+  # Use the ShipCompliant::SearchSalesOrdersResult#remaining_orders_length method in
+  # conjunction with this method to page through the result set.
+  #
+  # _You must specify at least one of the date range options or an invoice number range in this request._
+  #
+  #   orders = ShipCompliant::SearchSalesOrders.find_by({
+  #     purchase_date_min: DateTime.new(2014, 3, 10),
+  #     purchase_date_max: DateTime.new(2014, 3, 12)
+  #   })
+  class SearchSalesOrders
+
+    # +query+ must be a Hash with the keys relating to each search criteria.
+    #
+    # To see a list of available keys take a look at OrderSearch::KEYS
+    # 
+    #   # find orders place within date
+    #   orders = ShipCompliant::SearchSalesOrders.find_by({
+    #     purchase_date_min: DateTime.new(2014, 3, 10),
+    #     purchase_date_max: DateTime.new(2014, 3, 12)
+    #   })
+    #
+    #   # find orders by compliance_status
+    #   orders = ShipCompliant::SearchSalesOrders.find_by({
+    #     compliance_status: 'NotCompliant' # possible values are "Compliant", "NotCompliant", or "Any". Any is default.
+    #   })
+    def self.find_by(query)
+      order_query = OrderSearch.new(query).to_h
+
+      sales = search_sales(order_query)
+      SearchSalesOrdersResult.new(sales.to_hash)
+    end
+
+    private
+    
+    def self.search_sales(order_query)
+      ShipCompliant.client.call(:search_sales_orders, order_query)
+    end
+
+  end
+end

data/lib/ship_compliant/search_sales_orders_result.rb

@@ -0,0 +1,106 @@
+module ShipCompliant
+  # === An API wrapper for +SearchSalesOrders+ response.
+  #
+  # Converts fields into integers and ensures +order_summaries+
+  # is an array.
+  #
+  #   orders = ShipCompliant::SearchSalesOrders.find_by({
+  #     purchase_date_min: DateTime.new(2014, 3, 10),
+  #     purchase_date_max: DateTime.new(2014, 3, 12)
+  #   })
+  #
+  #   puts orders.length #=> 2
+  #
+  #   orders.summaries.each do |summary|
+  #     puts summary.purchase_date #=> DateTime
+  #   end
+  class SearchSalesOrdersResult
+    include BaseResult
+    attr_reader :raw
+    alias_method :response, :raw # for BaseResult
+
+    def initialize(data)
+      @raw = data
+      parse!
+    end
+
+    # The number of orders returned the current response.
+    def length
+      raw.fetch(:count_sales_orders_returned, 0)
+    end
+
+    # The number of orders waiting to be returned.
+    # Use this for paging results.
+    def remaining_orders_length
+      raw.fetch(:count_more_sales_orders_available, 0)
+    end
+
+    # Returns an array of ShipCompliant::SearchSalesOrderSummary.
+    # Use this to get information about each order.
+    #
+    #   orders.summaries.each do |summary|
+    #     puts summary.purchase_date #=> DateTime
+    #   end
+    def summaries
+      raw[:sales_orders][:sales_order_summary].reject(&:blank?).map do |summary|
+        SearchSalesOrderSummary.new(summary)
+      end
+    end
+
+    # Returns the +PagingCookie+ node.
+    def paging_cookie
+      response[:paging_cookie]
+    end
+
+    # Returns the +PagingCookieExpires+ node as DateTime.
+    def paging_cookie_expires
+      response[:paging_cookie_expires]
+    end
+
+    private
+
+    # Standardizes the XML response by converting fields to integers
+    # and forcing the order summaries into an array.
+    def parse!
+      unless raw.has_key?(:sales_orders)
+        raw[:sales_orders] = {}
+      end
+
+      # force orders to be an array
+      orders = raw[:sales_orders].fetch(:sales_order_summary, {})
+      unless orders.kind_of?(Array)
+        raw[:sales_orders][:sales_order_summary] = [orders]
+      end
+
+      # typecast :count_more_sales_orders_available to integer
+      if raw.has_key?(:count_more_sales_orders_available)
+        convert_to_integer!(:count_more_sales_orders_available, raw)
+      end
+
+      # typecast :count_sales_orders_returned to integer
+      if raw.has_key?(:count_sales_orders_returned)
+        convert_to_integer!(:count_sales_orders_returned, raw)
+      end
+
+      raw[:sales_orders][:sales_order_summary].each do |summary|
+
+        # typecast :shipment_key to integer
+        if summary.fetch(:shipments, {}).fetch(:shipment_summary, {}).has_key?(:shipment_key)
+          convert_to_integer!(:shipment_key, summary[:shipments][:shipment_summary])
+        end
+
+        # typecast :zip1 to integer
+        if summary.fetch(:shipments, {}).fetch(:shipment_summary, {}).fetch(:ship_to, {}).has_key?(:zip1)
+          convert_to_integer!(:zip1, summary[:shipments][:shipment_summary][:ship_to])
+        end
+      end
+    end
+
+    # Typecasts an object key into to an integer.
+    #
+    #   convert_to_integer(:shipment_key, order_summary[:shipments][:shipment_summary])
+    def convert_to_integer!(key, object)
+      object[key] = object[key].to_i
+    end
+  end
+end

data/lib/ship_compliant/shipment.rb

@@ -0,0 +1,59 @@
+module ShipCompliant
+  class Shipment < Struct.new(:shipment)
+
+    def fulfillment_house
+      shipment[:fulfillment_house]
+    end
+
+    def fulfillment_exception_reason
+      shipment[:fulfillment_exception_reason]
+    end
+
+    def fulfillment_exception_type
+      shipment[:fulfillment_exception_type]
+    end
+
+    def fulfillment_status
+      shipment[:fulfillment_status]
+    end
+
+    def handling
+      shipment[:handling].to_f
+    end
+
+    def insured_amount
+      shipment[:insured_amount].to_f
+    end
+
+    def shipping
+      shipment[:shipping].to_f
+    end
+
+    def ship_date
+      shipment[:ship_date]
+    end
+
+    def shipment_status
+      shipment[:shipment_status]
+    end
+
+    def shipping_service
+      shipment[:shipping_service]
+    end
+
+    def special_instructions
+      shipment[:special_instructions]
+    end
+
+    def packages
+      Array.wrap(shipment[:packages]).map do |package|
+        Package.new(package[:package])
+      end
+    end
+
+    def ship_to
+      Address.new(shipment[:ship_to])
+    end
+
+  end
+end