shippinglogic 1.2.3

data/lib/shippinglogic/ups/request.rb

@@ -0,0 +1,49 @@
+require "builder"
+
+module Shippinglogic
+  class UPS
+    # Methods relating to building and sending a request to UPS's web services.
+    module Request
+      private
+        # Convenience method for sending requests to UPS
+        def request(body)
+          real_class.post(base.url + real_class.path, :body => body)
+        end
+        
+        # Convenience method to create a builder object so that our builder options are consistent across
+        # the various services.
+        #
+        # Ex: if I want to change the indent level to 3 it should change for all requests built.
+        def builder
+          b = Builder::XmlMarkup.new(:indent => 2)
+          b.instruct!
+          b
+        end
+        
+        # A convenience method for building the authentication block in your XML request
+        def build_authentication(b)
+          b.AccessRequest(:"xml:lang" => "en-US") do
+            b.AccessLicenseNumber base.key
+            b.UserId base.account
+            b.Password base.password
+          end
+        end
+        
+        # A convenience method for building the address block in your XML request
+        def build_address(b, type)
+          address_lines = send("#{type}_streets").to_s.split(/(?:\s*\n\s*)+/m, 3)
+          
+          b.Address do
+            b.AddressLine1 address_lines[0] if address_lines[0]
+            b.AddressLine2 address_lines[1] if address_lines[1]
+            b.AddressLine3 address_lines[2] if address_lines[2]
+            b.City send("#{type}_city") if send("#{type}_city")
+            b.StateProvinceCode send("#{type}_state") if send("#{type}_state")
+            b.PostalCode send("#{type}_postal_code") if send("#{type}_postal_code")
+            b.CountryCode send("#{type}_country") if send("#{type}_country")
+            b.ResidentialAddressIndicator attribute_names.include?("#{type}_residential") && send("#{type}_residential")
+          end
+        end
+    end
+  end
+end

data/lib/shippinglogic/ups/response.rb

@@ -0,0 +1,58 @@
+require "shippinglogic/ups/error"
+
+module Shippinglogic
+  class UPS
+    # Methods relating to receiving a response from UPS and cleaning it up.
+    module Response
+      SUCCESSFUL_SEVERITIES = ["Warning"]
+      
+      private
+        # Overwriting the request method to clean the response and handle errors.
+        def request(body)
+          response = clean_response(super)
+          
+          if success?(response)
+            response
+          else
+            raise Error.new(body, response)
+          end
+        end
+        
+        # Was the response a success?
+        def success?(response)
+          response.is_a?(Hash) && response[:response][:response_status_code] == "1"
+        end
+        
+        # Cleans the response and returns it in a more 'user friendly' format that is easier
+        # to work with.
+        def clean_response(response)
+          cut_to_the_chase(sanitize_response_keys(response))
+        end
+        
+        # UPS likes nested XML tags, because they send quite a bit of them back in responses.
+        # This method just 'cuts to the chase' and get to the heart of the response.
+        def cut_to_the_chase(response)
+          response.values.first
+        end
+        
+        # Recursively sanitizes the response object by clenaing up any hash keys.
+        def sanitize_response_keys(response)
+          if response.is_a?(Hash)
+            response.inject({}) do |r, (key, value)|
+              r[sanitize_response_key(key)] = sanitize_response_keys(value)
+              r
+            end
+          elsif response.is_a?(Array)
+            response.collect { |r| sanitize_response_keys(r) }
+          else
+            response
+          end
+        end
+
+        # Underscores and symbolizes incoming UPS response keys.
+        def sanitize_response_key(key)
+          key.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+        end
+    end
+  end
+end

data/lib/shippinglogic/ups/service.rb

@@ -0,0 +1,11 @@
+require "shippinglogic/ups/request"
+require "shippinglogic/ups/response"
+
+module Shippinglogic
+  class UPS
+    class Service < Shippinglogic::Service
+      include Request
+      include Response
+    end
+  end
+end

data/lib/shippinglogic/ups/ship_accept.rb

@@ -0,0 +1,53 @@
+require "base64"
+
+module Shippinglogic
+  class UPS
+    class ShipAccept < Service
+      def self.path
+        "/ShipAccept"
+      end
+      
+      class Details
+        class Shipment; attr_accessor :tracking_number, :label; end
+        
+        attr_accessor :rate, :currency, :shipments
+        
+        def initialize(response)
+          details = response[:shipment_results]
+          
+          charges       = details[:shipment_charges][:total_charges]
+          self.rate     = BigDecimal.new(charges[:monetary_value])
+          self.currency = charges[:currency_code]
+          
+          self.shipments = [*details[:package_results]].collect do |package|
+            shipment                  = Shipment.new
+            shipment.tracking_number  = package[:tracking_number]
+            shipment.label            = Base64.decode64(package[:label_image][:graphic_image])
+            shipment
+          end
+        end
+      end
+      
+      attribute :digest, :string
+      
+      private
+        def target
+          @target ||= Details.new(request(build_request))
+        end
+        
+        def build_request
+          b = builder
+          build_authentication(b)
+          b.instruct!
+          
+          b.ShipmentAcceptRequest do
+            b.Request do
+              b.RequestAction "ShipAccept"
+            end
+            
+            b.ShipmentDigest digest
+          end
+        end
+    end
+  end
+end

data/lib/shippinglogic/ups/ship_confirm.rb

@@ -0,0 +1,170 @@
+module Shippinglogic
+  class UPS
+    class ShipConfirm < Service
+      def self.path
+        "/ShipConfirm"
+      end
+      
+      class Details
+        attr_accessor :digest, :tracking_number, :rate, :currency
+        
+        def initialize(response)
+          self.digest           = response[:shipment_digest]
+          self.tracking_number  = response[:shipment_identification_number]
+          
+          charges       = response[:shipment_charges][:total_charges]
+          self.rate     = BigDecimal.new(charges[:monetary_value])
+          self.currency = charges[:currency_code]
+        end
+      end
+      
+      # shipper options
+      attribute :shipper_name,                :string
+      attribute :shipper_phone_number,        :string
+      attribute :shipper_email,               :string
+      attribute :shipper_streets,             :string
+      attribute :shipper_city,                :string
+      attribute :shipper_state,               :string
+      attribute :shipper_postal_code,         :string
+      attribute :shipper_country,             :string
+      
+      # recipient options
+      attribute :recipient_name,              :string
+      attribute :recipient_phone_number,      :string
+      attribute :recipient_email,             :string
+      attribute :recipient_streets,           :string
+      attribute :recipient_city,              :string
+      attribute :recipient_state,             :string
+      attribute :recipient_postal_code,       :string
+      attribute :recipient_country,           :string
+      attribute :recipient_residential,       :boolean,     :default => false
+      
+      # label options
+      attribute :label_format,                :string,      :default => "GIF"
+      attribute :label_file_type,             :string,      :default => "GIF"
+      
+      # packaging options
+      attribute :packaging_type,              :string,      :default => "00"
+      attribute :package_count,               :integer,     :default => 1
+      attribute :package_weight,              :float
+      attribute :package_weight_units,        :string,      :default => "LBS"
+      attribute :package_length,              :integer
+      attribute :package_width,               :integer
+      attribute :package_height,              :integer
+      attribute :package_dimension_units,     :string,      :default => "IN"
+      
+      # monetary options
+      attribute :currency_type,               :string
+      attribute :insured_value,               :decimal
+      attribute :payor_account_number,        :string,      :default => lambda { |shipment| shipment.base.number }
+      
+      # delivery options
+      attribute :service_type,                :string
+      #FIXME Setting the signature option to true raises and error. I believe this has something
+      # to do with UPS account-specific settings and signature service availability.
+      attribute :signature,                   :boolean,     :default => false
+      attribute :saturday,                    :boolean,     :default => false
+      
+      private
+        def target
+          @target ||= Details.new(request(build_request))
+        end
+        
+        def build_request
+          b = builder
+          build_authentication(b)
+          b.instruct!
+          
+          b.ShipmentConfirmRequest do
+            b.Request do
+              b.RequestAction "ShipConfirm"
+              b.RequestOption "validate"
+            end
+            
+            b.Shipment do
+              b.Shipper do
+                b.Name shipper_name
+                b.ShipperNumber payor_account_number
+                b.PhoneNumber shipper_phone_number
+                b.EMailAddress shipper_email
+                build_address(b, :shipper)
+              end
+              
+              b.ShipTo do
+                b.CompanyName recipient_name
+                b.PhoneNumber recipient_phone_number
+                b.EMailAddress recipient_email
+                build_address(b, :recipient)
+              end
+              
+              b.PaymentInformation do
+                b.Prepaid do
+                  b.BillShipper do
+                    b.AccountNumber payor_account_number
+                  end
+                end
+              end
+              
+              b.Service do
+                b.Code service_type
+              end
+              
+              b.ShipmentServiceOptions do
+                b.SaturdayDelivery if saturday
+                if signature
+                  b.DeliveryConfirmation do
+                    b.DCISType "1"
+                  end
+                end
+              end
+              
+              package_count.times do |i|
+                b.Package do
+                  b.PackagingType do
+                    b.Code packaging_type
+                  end
+                  
+                  b.Dimensions do
+                    b.UnitOfMeasurement do
+                      b.Code package_dimension_units
+                    end
+                    
+                    b.Length "%.2f" % package_length
+                    b.Width "%.2f" % package_width
+                    b.Height "%.2f" % package_height
+                  end
+                  
+                  b.PackageWeight do
+                    b.UnitOfMeasurement do
+                      b.Code package_weight_units
+                    end
+                    
+                    b.Weight "%.1f" % package_weight
+                  end
+                  
+                  b.PackageServiceOptions do
+                    if insured_value
+                      b.InsuredValue do
+                        b.MonetaryValue insured_value
+                        b.CurrencyCode currency_type
+                      end
+                    end
+                  end
+                end
+              end
+            end
+            
+            b.LabelSpecification do
+              b.LabelPrintMethod do
+                b.Code label_file_type
+              end
+              
+              b.LabelImageFormat do
+                b.Code label_format
+              end
+            end
+          end
+        end
+    end
+  end
+end

data/lib/shippinglogic/ups/track.rb

@@ -0,0 +1,118 @@
+module Shippinglogic
+  class UPS
+    # An interface to the track services provided by UPS. Allows you to get an array of events for a specific
+    # tracking number.
+    #
+    # == Accessor methods / options
+    #
+    # * <tt>tracking_number</tt> - the tracking number
+    #
+    # === Simple Example
+    #
+    # Here is a very simple example:
+    #
+    #   ups = Shippinglogic::UPS.new(key, password, account)
+    #   tracking_details = ups.track(:tracking_number => "my number")
+    #
+    #   tracking_details.status
+    #   # => "Delivered"
+    #   
+    #   tracking_details.signature_name
+    #   # => "KKING"
+    #   
+    #   tracking_details.events.first
+    #   # => #<Shippinglogic::UPS::Track::Event @postal_code="95817", @name="Delivered", @state="CA",
+    #   #     @city="Sacramento", @type="Delivered", @country="US", @occured_at=Mon Dec 08 10:43:37 -0500 2008>
+    #   
+    #   tracking_details.events.first.name
+    #   # => "Delivered"
+    #
+    # === Note
+    #
+    # UPS does support locating packages through means other than a tracking number.
+    # These are not supported and probably won't be until someone needs them. It should
+    # be fairly simple to add, but I could not think of a reason why anyone would want to track
+    # a package with anything other than a tracking number.
+    class Track < Service
+      def self.path
+        "/Track"
+      end
+      
+      class Details
+        # Each tracking result is an object of this class
+        class Event; attr_accessor :name, :type, :occured_at, :city, :state, :postal_code, :country; end
+        
+        attr_accessor :origin_city, :origin_state, :origin_country,
+          :destination_city, :destination_state, :destination_country,
+          :signature_name, :service_type, :status, :delivery_at,
+          :events
+        
+        def initialize(response)
+          details = response[:shipment]
+          
+          if origin = details.fetch(:shipper, {})[:address]
+            self.origin_city    = origin[:city]
+            self.origin_state   = origin[:state_province_code]
+            self.origin_country = origin[:country_code]
+          end
+          
+          if destination = details.fetch(:ship_to, {})[:address]
+            self.destination_city     = destination[:city]
+            self.destination_state    = destination[:state_province_code]
+            self.destination_country  = destination[:country_code]
+          end
+          
+          package     = details[:package]
+          events      = package[:activity].is_a?(Array) ? package[:activity] : [package[:activitiy]].compact
+          last_event  = events.first
+          delivery    = events.detect{|e| e[:status][:status_type][:code] == "D" }
+          
+          self.signature_name = last_event && last_event[:signed_for_by_name]
+          self.service_type   = details[:service][:description]
+          self.status         = last_event && last_event[:status][:status_type][:description]
+          self.delivery_at    = delivery && Time.parse(delivery[:date] + delivery[:time])
+          
+          self.events = events.collect do |details|
+            event             = Event.new
+            status            = details[:status][:status_type]
+            event.name        = status[:description]
+            event.type        = status[:code]
+            #FIXME The proper spelling is "occurred", not "occured."
+            event.occured_at  = Time.parse(details[:date] + details[:time])
+            location          = details[:activity_location][:address]
+            event.city        = location[:city]
+            event.state       = location[:state_province_code]
+            event.postal_code = location[:postal_code]
+            event.country     = location[:country_code]
+            event
+          end
+        end
+      end
+      
+      attribute :tracking_number, :string
+      
+      private
+        # The parent class Service requires that we define this method. This is our kicker. This method is only
+        # called when we need to deal with information from UPS. Notice the caching into the @target variable.
+        def target
+          @target ||= Details.new(request(build_request))
+        end
+        
+        # Just building some XML to send off to UPS. UPS requires this particualar format.
+        def build_request
+          b = builder
+          build_authentication(b)
+          b.instruct!
+          
+          b.TrackRequest do
+            b.Request do
+              b.RequestAction "Track"
+              b.RequestOption "activity"
+            end
+            
+            b.TrackingNumber tracking_number
+          end
+        end
+    end
+  end
+end