ups-ruby 0.8.3

data/lib/ups/builders/organisation_builder.rb

@@ -0,0 +1,74 @@
+require 'ox'
+
+module UPS
+  module Builders
+    # The {OrganisationBuilder} class builds UPS XML Organization Objects.
+    #
+    # @author Paul Trippett
+    # @since 0.1.0
+    # @attr [String] name The Containing XML Element Name
+    # @attr [Hash] opts The Organization and Address Parts
+    class OrganisationBuilder < BuilderBase
+      include Ox
+
+      attr_accessor :name, :opts
+
+      # Initializes a new {AddressBuilder} object
+      #
+      # @param [Hash] opts The Organization and Address Parts
+      # @option opts [String] :company_name Company Name
+      # @option opts [String] :phone_number Phone Number
+      # @option opts [String] :address_line_1 Address Line 1
+      # @option opts [String] :city City
+      # @option opts [String] :state State
+      # @option opts [String] :postal_code Zip or Postal Code
+      # @option opts [String] :country Country
+      def initialize(name, opts = {})
+        self.name = name
+        self.opts = opts
+      end
+
+      # Returns an XML representation of company_name
+      #
+      # @return [Ox::Element] XML representation of company_name
+      def company_name
+        element_with_value('CompanyName', opts[:company_name][0..34])
+      end
+
+      # Returns an XML representation of phone_number
+      #
+      # @return [Ox::Element] XML representation of phone_number
+      def phone_number
+        element_with_value('PhoneNumber', opts[:phone_number][0..14])
+      end
+
+      # Returns an XML representation of AttentionName for which we use company
+      # name
+      #
+      # @return [Ox::Element] XML representation of company_name part
+      def attention_name
+        element_with_value('AttentionName', opts[:attention_name][0..34])
+      end
+
+      # Returns an XML representation of address
+      #
+      # @return [Ox::Element] An instance of {AddressBuilder} containing the
+      #   address
+      def address
+        AddressBuilder.new(opts).to_xml
+      end
+
+      # Returns an XML representation of a UPS Organization
+      #
+      # @return [Ox::Element] XML representation of the current object
+      def to_xml
+        Element.new(name).tap do |org|
+          org << company_name
+          org << phone_number
+          org << attention_name
+          org << address
+        end
+      end
+    end
+  end
+end

data/lib/ups/builders/rate_builder.rb

@@ -0,0 +1,21 @@
+require 'ox'
+
+module UPS
+  module Builders
+    # The {RateBuilder} class builds UPS XML Rate Objects.
+    #
+    # @author Paul Trippett
+    # @since 0.1.0
+    class RateBuilder < BuilderBase
+      include Ox
+
+      # Initializes a new {RateBuilder} object
+      #
+      def initialize
+        super 'RatingServiceSelectionRequest'
+
+        add_request('Rate', 'Shop')
+      end
+    end
+  end
+end

data/lib/ups/builders/ship_accept_builder.rb

@@ -0,0 +1,30 @@
+require 'ox'
+
+module UPS
+  module Builders
+    # The {ShipAcceptBuilder} class builds UPS XML ShipAccept Objects.
+    #
+    # @author Paul Trippett
+    # @since 0.1.0
+    class ShipAcceptBuilder < BuilderBase
+      include Ox
+
+      # Initializes a new {ShipAcceptBuilder} object
+      #
+      def initialize
+        super 'ShipmentAcceptRequest'
+
+        add_request 'ShipAccept', '1'
+      end
+
+      # Adds a ShipmentDigest section to the XML document being built
+      #
+      # @param [String] digest The UPS Shipment Digest returned from the
+      #   ShipConfirm request
+      # @return [void]
+      def add_shipment_digest(digest)
+        root << element_with_value('ShipmentDigest', digest)
+      end
+    end
+  end
+end

data/lib/ups/builders/ship_confirm_builder.rb

@@ -0,0 +1,103 @@
+require 'ox'
+
+module UPS
+  module Builders
+    # The {ShipConfirmBuilder} class builds UPS XML ShipConfirm Objects.
+    #
+    # @author Paul Trippett
+    # @since 0.1.0
+    # @attr [String] name The Containing XML Element Name
+    # @attr [Hash] opts The Organization and Address Parts
+    class ShipConfirmBuilder < BuilderBase
+      include Ox
+
+      # Initializes a new {ShipConfirmBuilder} object
+      #
+      def initialize
+        super 'ShipmentConfirmRequest'
+
+        add_request 'ShipConfirm', 'validate'
+      end
+
+      # Adds a LabelSpecification section to the XML document being built
+      # according to user inputs
+      #
+      # @return [void]
+      def add_label_specification(format, size)
+        root << Element.new('LabelSpecification').tap do |label_spec|
+          label_spec << label_print_method(format)
+          label_spec << label_image_format(format)
+          label_spec << label_stock_size(size)
+          label_spec << http_user_agent if gif?(format)
+        end
+      end
+
+      # Adds a Service section to the XML document being built
+      #
+      # @param [String] service_code The Service code for the choosen Shipping
+      #   method
+      # @param [optional, String] service_description A description for the
+      #   choosen Shipping Method
+      # @return [void]
+      def add_service(service_code, service_description = '')
+        shipment_root << code_description('Service',
+                                          service_code,
+                                          service_description)
+      end
+
+      # Adds Description to XML document being built
+      #
+      # @param [String] description The description for goods being sent
+      #
+      # @return [void]
+      def add_description(description)
+        shipment_root << element_with_value('Description', description)
+      end
+
+      # Adds ReferenceNumber to the XML document being built
+      #
+      # @param [Hash] opts A Hash of data to build the requested section
+      # @option opts [String] :code Code
+      # @option opts [String] :value Value
+      #
+      # @return [void]
+      def add_reference_number(opts = {})
+        shipment_root << reference_number(opts[:code], opts[:value])
+      end
+
+      private
+
+      def gif?(string)
+        string.downcase == 'gif'
+      end
+
+      def http_user_agent
+        element_with_value('HTTPUserAgent', version_string)
+      end
+
+      def version_string
+        "RubyUPS/#{UPS::Version::STRING}"
+      end
+
+      def label_print_method(format)
+        code_description 'LabelPrintMethod', "#{format}", "#{format} file"
+      end
+
+      def label_image_format(format)
+        code_description 'LabelImageFormat', "#{format}", "#{format}"
+      end
+
+      def label_stock_size(size)
+        multi_valued('LabelStockSize',
+                     'Height' => size[:height].to_s,
+                     'Width' => size[:width].to_s)
+      end
+
+      def reference_number(code, value)
+        multi_valued('ReferenceNumber',
+                     'Code' => code.to_s,
+                     'Value' => value.to_s)
+      end
+    end
+  end
+end

data/lib/ups/builders/shipper_builder.rb

@@ -0,0 +1,88 @@
+require 'ox'
+
+module UPS
+  module Builders
+    # The {ShipperBuilder} class builds UPS XML Organization Objects.
+    #
+    # @author Paul Trippett
+    # @since 0.1.0
+    # @attr [String] name The Containing XML Element Name
+    # @attr [Hash] opts The Shipper and Address Parts
+    class ShipperBuilder < BuilderBase
+      include Ox
+
+      attr_accessor :name, :opts
+
+      # Initializes a new {ShipperBuilder} object
+      #
+      # @param [Hash] opts The Shipper and Address Parts
+      # @option opts [String] :company_name Company Name
+      # @option opts [String] :phone_number Phone Number
+      # @option opts [String] :address_line_1 Address Line 1
+      # @option opts [String] :city City
+      # @option opts [String] :state State
+      # @option opts [String] :postal_code Zip or Postal Code
+      # @option opts [String] :country Country
+      def initialize(opts = {})
+        self.name = name
+        self.opts = opts
+      end
+
+      # Returns an XML representation of shipper_name
+      #
+      # @return [Ox::Element] XML representation of shipper_name
+      def shipper_name
+        element_with_value('Name', opts[:company_name])
+      end
+
+      # Returns an XML representation of company_name
+      #
+      # @return [Ox::Element] XML representation of company_name
+      def company_name
+        element_with_value('CompanyName', opts[:company_name])
+      end
+
+      # Returns an XML representation of company_name
+      #
+      # @return [Ox::Element] XML representation of phone_number
+      def phone_number
+        element_with_value('PhoneNumber', opts[:phone_number])
+      end
+
+      # Returns an XML representation of company_name
+      #
+      # @return [Ox::Element] XML representation of shipper_number
+      def shipper_number
+        element_with_value('ShipperNumber', opts[:shipper_number] || '')
+      end
+
+      # Returns an XML representation of the associated Address
+      #
+      # @return [Ox::Element] XML object of the associated Address
+      def address
+        AddressBuilder.new(opts).to_xml
+      end
+
+      # Returns an XML representation of attention_name
+      #
+      # @return [Ox::Element] XML representation of attention_name
+      def attention_name
+        element_with_value('AttentionName', opts[:attention_name] || '')
+      end
+
+      # Returns an XML representation of the current object
+      #
+      # @return [Ox::Element] XML representation of the current object
+      def to_xml
+        Element.new('Shipper').tap do |org|
+          org << shipper_name
+          org << attention_name
+          org << company_name
+          org << phone_number
+          org << shipper_number
+          org << address
+        end
+      end
+    end
+  end
+end

data/lib/ups/connection.rb

@@ -0,0 +1,124 @@
+require 'uri'
+require 'excon'
+require 'digest/md5'
+require 'ox'
+
+module UPS
+  # The {Connection} class acts as the main entry point to performing rate and
+  # ship operations against the UPS API.
+  #
+  # @author Paul Trippett
+  # @abstract
+  # @since 0.1.0
+  # @attr [String] url The base url to use either TEST_URL or LIVE_URL
+  class Connection
+    attr_accessor :url
+
+    TEST_URL = 'https://wwwcie.ups.com'
+    LIVE_URL = 'https://onlinetools.ups.com'
+
+    RATE_PATH = '/ups.app/xml/Rate'
+    SHIP_CONFIRM_PATH = '/ups.app/xml/ShipConfirm'
+    SHIP_ACCEPT_PATH = '/ups.app/xml/ShipAccept'
+    ADDRESS_PATH = '/ups.app/xml/XAV'
+
+    DEFAULT_PARAMS = {
+      test_mode: false
+    }
+
+    # Initializes a new {Connection} object
+    #
+    # @param [Hash] params The initialization options
+    # @option params [Boolean] :test_mode If TEST_URL should be used for
+    #   requests to the UPS URL
+    def initialize(params = {})
+      params = DEFAULT_PARAMS.merge(params)
+      self.url = (params[:test_mode]) ? TEST_URL : LIVE_URL
+    end
+
+    # Makes a request to fetch Rates for a shipment.
+    #
+    # A pre-configured {Builders::RateBuilder} object can be passed as the first
+    # option or a block yielded to configure a new {Builders::RateBuilder}
+    # object.
+    #
+    # @param [Builders::RateBuilder] rate_builder A pre-configured
+    #   {Builders::RateBuilder} object to use
+    # @yield [rate_builder] A RateBuilder object for configuring
+    #   the shipment information sent
+    def rates(rate_builder = nil)
+      if rate_builder.nil? && block_given?
+        rate_builder = UPS::Builders::RateBuilder.new
+        yield rate_builder
+      end
+
+      response = get_response_stream RATE_PATH, rate_builder.to_xml
+      UPS::Parsers::RatesParser.new.tap do |parser|
+        Ox.sax_parse(parser, response)
+      end
+    end
+
+    # Makes a request to ship a package
+    #
+    # A pre-configured {Builders::ShipConfirmBuilder} object can be passed as
+    # the first option or a block yielded to configure a new
+    # {Builders::ShipConfirmBuilder} object.
+    #
+    # @param [Builders::ShipConfirmBuilder] confirm_builder A pre-configured
+    #   {Builders::ShipConfirmBuilder} object to use
+    # @yield [ship_confirm_builder] A ShipConfirmBuilder object for configuring
+    #   the shipment information sent
+    def ship(confirm_builder = nil)
+      if confirm_builder.nil? && block_given?
+        confirm_builder = Builders::ShipConfirmBuilder.new
+        yield confirm_builder
+      end
+
+      confirm_response = make_confirm_request(confirm_builder)
+      return confirm_response unless confirm_response.success?
+
+      accept_builder = build_accept_request_from_confirm(confirm_builder,
+                                                         confirm_response)
+      make_accept_request accept_builder
+    end
+
+    private
+
+    def build_url(path)
+      "#{url}#{path}"
+    end
+
+    def get_response_stream(path, body)
+      response = Excon.post(build_url(path), body: body)
+      StringIO.new(response.body)
+    end
+
+    def make_confirm_request(confirm_builder)
+      make_ship_request confirm_builder,
+                        SHIP_CONFIRM_PATH,
+                        Parsers::ShipConfirmParser.new
+    end
+
+    def make_accept_request(accept_builder)
+      make_ship_request accept_builder,
+                        SHIP_ACCEPT_PATH,
+                        Parsers::ShipAcceptParser.new
+    end
+
+    def make_ship_request(builder, path, ship_parser)
+      response = get_response_stream path, builder.to_xml
+      ship_parser.tap do |parser|
+        Ox.sax_parse(parser, response)
+      end
+    end
+
+    def build_accept_request_from_confirm(confirm_builder, confirm_response)
+      UPS::Builders::ShipAcceptBuilder.new.tap do |builder|
+        builder.add_access_request confirm_builder.license_number,
+                                   confirm_builder.user_id,
+                                   confirm_builder.password
+        builder.add_shipment_digest confirm_response.shipment_digest
+      end
+    end
+  end
+end

data/lib/ups/data.rb

@@ -0,0 +1,50 @@
+require 'levenshtein'
+
+module UPS
+  module Data
+    class << self
+      EMPTY_STATE_MESSAGE = 'Invalid Address State [:state]'
+
+      # Normalizes Irish states as per UPS requirements
+      #
+      # @param [String] string The Irish State to normalize
+      # @return [String] The normalized Irish state name
+      def ie_state_normalizer(string)
+        string.tap do |target|
+          IE_COUNTY_PREFIXES.each do |prefix|
+            target.gsub!(/^#{Regexp.escape(prefix.downcase)} /i, '')
+          end
+        end
+      end
+
+      # Returns the closest matching Irish state name. Uses Levenshtein
+      # distance to correct any possible spelling errors.
+      #
+      # @param [String] match_string The Irish State to match
+      # @raise [InvalidAttributeError] If the passed match_String is nil or
+      #   empty
+      # @return [String] The closest matching irish state with the specified
+      #   name
+      def ie_state_matcher(match_string)
+        fail Exceptions::InvalidAttributeError, EMPTY_STATE_MESSAGE if
+          match_string.nil? || match_string.empty?
+
+        normalized_string = ie_state_normalizer string_normalizer match_string
+        counties_with_distances = IE_COUNTIES.map do |county|
+          [county, Levenshtein.distance(county.downcase, normalized_string)]
+        end
+        counties_with_distances_hash = Hash[*counties_with_distances.flatten]
+        counties_with_distances_hash.min_by { |_k, v| v }[0]
+      end
+
+      # Removes extra characters from a string
+      #
+      # @param [String] string The string to normalize and remove special
+      #   characters
+      # @return [String] The normalized string
+      def string_normalizer(string)
+        string.downcase.gsub(/[^0-9a-z ]/i, '')
+      end
+    end
+  end
+end