shippinglogic 1.2.3

data/lib/shippinglogic/fedex/error.rb

@@ -0,0 +1,47 @@
+module Shippinglogic
+  class FedEx
+    # If FedEx responds with an error, we try our best to pull the pertinent information out of that
+    # response and raise it with this object. Any time FedEx says there is a problem an object of this
+    # class will be raised.
+    #
+    # === Tip
+    #
+    # If you want to see the raw request / respose catch the error object and call the request / response method. Ex:
+    #
+    #   begin
+    #     # my fedex code
+    #   rescue Shippinglogic::FedEx::Error => e
+    #     # do whatever you want here, just do:
+    #     # e.request
+    #     # e.response
+    #     # to get the raw response from fedex
+    #   end
+    class Error < Shippinglogic::Error
+      def initialize(request, response)
+        super
+        
+        if response.blank?
+          add_error("The response from FedEx was blank.")
+        elsif !response.is_a?(Hash)
+          add_error("The response from FedEx was malformed and was not in a valid XML format.")
+        elsif notifications = response[:notifications]
+          notifications = notifications.is_a?(Array) ? notifications : [notifications]
+          notifications.delete_if { |notification| Response::SUCCESSFUL_SEVERITIES.include?(notification[:severity]) }
+          notifications.each { |notification| add_error(notification[:message], notification[:code]) }
+        elsif response[:"soapenv:fault"] && detail = response[:"soapenv:fault"][:detail][:"con:fault"]
+          add_error(detail[:"con:reason"], detail[:"con:error_code"])
+          
+          if detail[:"con:details"] && detail[:"con:details"][:"con1:validation_failure_detail"] && messages = detail[:"con:details"][:"con1:validation_failure_detail"][:"con1:message"]
+            messages = messages.is_a?(Array) ? messages : [messages]
+            messages.each { |message| add_error(message) }
+          end
+        else
+          add_error(
+            "There was a problem with your fedex request, and we couldn't locate a specific error message. This means your response " +
+            "was in an unexpected format. You might try glancing at the raw response by using the 'response' method on this error object."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/shippinglogic/fedex/rate.rb

@@ -0,0 +1,229 @@
+module Shippinglogic
+  class FedEx
+    # An interface to the rate services provided by FedEx. Allows you to get an array of rates from fedex for a shipment,
+    # or a single rate for a specific service.
+    #
+    # == Options
+    # === Shipper options
+    #
+    # * <tt>shipper_name</tt> - name of the shipper.
+    # * <tt>shipper_title</tt> - title of the shipper.
+    # * <tt>shipper_company_name</tt> - company name of the shipper.
+    # * <tt>shipper_phone_number</tt> - phone number of the shipper.
+    # * <tt>shipper_email</tt> - email of the shipper.
+    # * <tt>shipper_streets</tt> - street part of the address, separate multiple streets with a new line, dont include blank lines.
+    # * <tt>shipper_city</tt> - city part of the address.
+    # * <tt>shipper_state_</tt> - state part of the address, use state abreviations.
+    # * <tt>shipper_postal_code</tt> - postal code part of the address. Ex: zip for the US.
+    # * <tt>shipper_country</tt> - country code part of the address. FedEx expects abbreviations, but Shippinglogic will convert full names to abbreviations for you.
+    # * <tt>shipper_residential</tt> - a boolean value representing if the address is redential or not (default: false)
+    #
+    # === Recipient options
+    #
+    # * <tt>recipient_name</tt> - name of the recipient.
+    # * <tt>recipient_title</tt> - title of the recipient.
+    # * <tt>recipient_company_name</tt> - company name of the recipient.
+    # * <tt>recipient_phone_number</tt> - phone number of the recipient.
+    # * <tt>recipient_email</tt> - email of the recipient.
+    # * <tt>recipient_streets</tt> - street part of the address, separate multiple streets with a new line, dont include blank lines.
+    # * <tt>recipient_city</tt> - city part of the address.
+    # * <tt>recipient_state</tt> - state part of the address, use state abreviations.
+    # * <tt>recipient_postal_code</tt> - postal code part of the address. Ex: zip for the US.
+    # * <tt>recipient_country</tt> - country code part of the address. FedEx expects abbreviations, but Shippinglogic will convert full names to abbreviations for you.
+    # * <tt>recipient_residential</tt> - a boolean value representing if the address is redential or not (default: false)
+    #
+    # === Packaging options
+    #
+    # One thing to note is that FedEx does support multiple package shipments. The problem is that all of the packages must be identical.
+    # FedEx specifically notes in their documentation that mutiple package specifications are not allowed. So your only option for a
+    # multi package shipment is to increase the package_count option and keep the dimensions and weight the same for all packages. Then again,
+    # the documentation for the FedEx web services is terrible, so I could be wrong. Any tests I tried resulted in an error though.
+    #
+    # * <tt>packaging_type</tt> - one of Enumerations::PACKAGE_TYPES. (default: YOUR_PACKAGING)
+    # * <tt>package_count</tt> - the number of packages in your shipment. (default: 1)
+    # * <tt>package_weight</tt> - a single packages weight.
+    # * <tt>package_weight_units</tt> - either LB or KG. (default: LB)
+    # * <tt>package_length</tt> - a single packages length, only required if using YOUR_PACKAGING for packaging_type.
+    # * <tt>package_width</tt> - a single packages width, only required if using YOUR_PACKAGING for packaging_type.
+    # * <tt>package_height</tt> - a single packages height, only required if using YOUR_PACKAGING for packaging_type.
+    # * <tt>package_dimension_units</tt> - either IN or CM. (default: IN)
+    #
+    # === Monetary options
+    #
+    # * <tt>currency_type</tt> - the type of currency. (default: nil, because FedEx will default to your account preferences)
+    # * <tt>insured_value</tt> - the value you want to insure, if any. (default: nil)
+    # * <tt>payment_type</tt> - one of Enumerations::PAYMENT_TYPES. (default: SENDER)
+    # * <tt>payor_account_number</tt> - if the account paying for this ship is different than the account you specified then
+    #   you can specify that here. (default: your account number)
+    # * <tt>payor_country</tt> - the country code for the account number. (default: US)
+    #
+    # === Delivery options
+    #
+    # * <tt>ship_time</tt> - a Time object representing when you want to ship the package. (default: Time.now)
+    # * <tt>service_type</tt> - one of Enumerations::SERVICE_TYPES, this is optional, leave this blank if you want a list of all
+    #   available services. (default: nil)
+    # * <tt>delivery_deadline</tt> - whether or not to include estimated transit times. (default: true)
+    # * <tt>dropoff_type</tt> - one of Enumerations::DROP_OFF_TYPES. (default: REGULAR_PICKUP)
+    # * <tt>special_services_requested</tt> - any exceptions or special services FedEx needs to be aware of, this should be
+    #   one or more of Enumerations::SPECIAL_SERVICES. (default: nil)
+    #
+    # === Misc options
+    #
+    # * <tt>rate_request_types</tt> - one or more of RATE_REQUEST_TYPES. (default: ACCOUNT)
+    # * <tt>include_transit_times</tt> - whether or not to include estimated transit times. (default: true)
+    #
+    # == Simple Example
+    #
+    # Here is a very simple example. Mix and match the options above to get more accurate rates:
+    #
+    #   fedex = Shippinglogic::FedEx.new(key, password, account, meter)
+    #   rates = fedex.rate(
+    #     :shipper_postal_code => "10007",
+    #     :shipper_country => "US",
+    #     :recipient_postal_code => "75201",
+    #     :recipient_country => "US",
+    #     :package_weight => 24,
+    #     :package_length => 12,
+    #     :package_width => 12,
+    #     :package_height => 12
+    #   )
+    #
+    #   rates.first
+    #   #<Shippinglogic::FedEx::Rates::Rate @currency="USD", @name="First Overnight", @cost=#<BigDecimal:19ea290,'0.7001E2',8(8)>,
+    #     @deadline=Fri Aug 07 08:00:00 -0400 2009, @type="FIRST_OVERNIGHT", @saturday=false>
+    #   
+    #   # to show accessor methods
+    #   rates.first.name
+    #   # => "First Overnight"
+    class Rate < Service
+      # Each rate result is an object of this class
+      class Service; attr_accessor :name, :type, :saturday, :delivered_by, :speed, :rate, :currency; end
+      
+      VERSION = {:major => 6, :intermediate => 0, :minor => 0}
+      
+      # shipper options
+      attribute :shipper_name,                :string
+      attribute :shipper_title,               :string
+      attribute :shipper_company_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,      :modifier => :country_code
+      attribute :shipper_residential,         :boolean,     :default => false
+      
+      # recipient options
+      attribute :recipient_name,              :string
+      attribute :recipient_title,             :string
+      attribute :recipient_company_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,      :modifier => :country_code
+      attribute :recipient_residential,       :boolean,     :default => false
+      
+      # packaging options
+      attribute :packaging_type,              :string,      :default => "YOUR_PACKAGING"
+      attribute :package_count,               :integer,     :default => 1
+      attribute :package_weight,              :float
+      attribute :package_weight_units,        :string,      :default => "LB"
+      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 :payment_type,                :string,      :default => "SENDER"
+      attribute :payor_account_number,        :string,      :default => lambda { |shipment| shipment.base.account }
+      attribute :payor_country,               :string
+      
+      # delivery options
+      attribute :ship_time,                   :datetime,    :default => lambda { |rate| Time.now }
+      attribute :service_type,                :string
+      attribute :delivery_deadline,           :datetime
+      attribute :dropoff_type,                :string,      :default => "REGULAR_PICKUP"
+      attribute :special_services_requested,  :array
+      
+      # misc options
+      attribute :rate_request_types,          :array,       :default => ["ACCOUNT"]
+      attribute :include_transit_times,       :boolean,     :default => true
+      
+      private
+        def target
+          @target ||= parse_response(request(build_request))
+        end
+        
+        def build_request
+          b = builder
+          xml = b.RateRequest(:xmlns => "http://fedex.com/ws/rate/v#{VERSION[:major]}") do
+            build_authentication(b)
+            build_version(b, "crs", VERSION[:major], VERSION[:intermediate], VERSION[:minor])
+            b.ReturnTransitAndCommit include_transit_times
+            b.SpecialServicesRequested special_services_requested.join(",") if special_services_requested.any?
+            
+            b.RequestedShipment do
+              b.ShipTimestamp ship_time.xmlschema if ship_time
+              b.ServiceType service_type if service_type
+              b.DropoffType dropoff_type if dropoff_type
+              b.PackagingType packaging_type if packaging_type
+              build_insured_value(b)
+              b.Shipper { build_address(b, :shipper) }
+              b.Recipient { build_address(b, :recipient) }
+              b.ShippingChargesPayment do
+                b.PaymentType payment_type if payment_type
+                b.Payor do
+                  b.AccountNumber payor_account_number if payor_account_number
+                  b.CountryCode payor_country if payor_country
+                end
+              end
+              b.RateRequestTypes rate_request_types.join(",") if rate_request_types
+              build_package(b)
+            end
+          end
+        end
+        
+        def parse_response(response)
+          return [] if !response[:rate_reply_details]
+          
+          response[:rate_reply_details].collect do |details|
+            shipment_detail = details[:rated_shipment_details].is_a?(Array) ? details[:rated_shipment_details].first : details[:rated_shipment_details]
+            cost = shipment_detail[:shipment_rate_detail][:total_net_charge]
+            
+            delivered_by = details[:delivery_timestamp] && Time.parse(details[:delivery_timestamp])
+            speed = case details[:service_type]
+            when /overnight/i
+              86400 # 1.day
+            when /2_day/i
+              172800 # 2.days
+            else
+              259200 # 3.days
+            end
+            
+            if meets_deadline?(delivered_by)
+              service = Service.new
+              service.name = details[:service_type].gsub("_", " ").gsub(/\b(\w)(\w*)/){ $1 + $2.downcase }
+              service.type = details[:service_type]
+              service.saturday = details[:applied_options] == "SATURDAY_DELIVERY"
+              service.delivered_by = delivered_by
+              service.speed = speed
+              service.rate = BigDecimal.new(cost[:amount])
+              service.currency = cost[:currency]
+              service
+            end
+          end.compact
+        end
+        
+        def meets_deadline?(delivered_by)
+          return true if !delivery_deadline
+          delivered_by && delivered_by <= delivery_deadline
+        end
+    end
+  end
+end

data/lib/shippinglogic/fedex/request.rb

@@ -0,0 +1,134 @@
+require "builder"
+
+module Shippinglogic
+  class FedEx
+    # Methods relating to building and sending a request to FedEx's web services.
+    module Request
+      private
+        # Convenience method for sending requests to FedEx
+        def request(body)
+          real_class.post(base.url, :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.WebAuthenticationDetail do
+            b.UserCredential do
+              b.Key base.key
+              b.Password base.password
+            end
+          end
+          
+          b.ClientDetail do
+            b.AccountNumber base.account
+            b.MeterNumber base.meter
+          end
+        end
+        
+        # A convenience method for building the version block in your XML request
+        def build_version(b, service, major, intermediate, minor)
+          b.Version do
+            b.ServiceId service
+            b.Major major
+            b.Intermediate intermediate
+            b.Minor minor
+          end
+        end
+        
+        # A convenience method for building the contact block in your XML request
+        def build_contact(b, type)
+          b.Contact do
+            b.PersonName send("#{type}_name") if send("#{type}_name")
+            b.Title send("#{type}_title") if send("#{type}_title")
+            b.CompanyName send("#{type}_company_name") if send("#{type}_company_name")
+            b.PhoneNumber send("#{type}_phone_number") if send("#{type}_phone_number")
+            b.EMailAddress send("#{type}_email") if send("#{type}_email")
+          end
+        end
+        
+        # A convenience method for building the address block in your XML request
+        def build_address(b, type)
+          b.Address do
+            b.StreetLines send("#{type}_streets") if send("#{type}_streets")
+            b.City send("#{type}_city") if send("#{type}_city")
+            b.StateOrProvinceCode state_code(send("#{type}_state")) if send("#{type}_state")
+            b.PostalCode send("#{type}_postal_code") if send("#{type}_postal_code")
+            b.CountryCode country_code(send("#{type}_country")) if send("#{type}_country")
+            b.Residential send("#{type}_residential")
+          end
+        end
+        
+        def build_insured_value(b)
+          if insured_value
+            b.TotalInsuredValue do
+              b.Currency currency_type
+              b.Amount insured_value
+            end
+          end
+        end
+        
+        # A convenience method for building the package block in your XML request
+        def build_package(b)
+          b.PackageCount package_count
+          
+          b.RequestedPackages do
+            b.SequenceNumber 1
+            
+            b.Weight do
+              b.Units package_weight_units
+              b.Value package_weight
+            end
+            
+            if custom_packaging?
+              b.Dimensions do
+                b.Length package_length
+                b.Width package_width
+                b.Height package_height
+                b.Units package_dimension_units
+              end
+            end
+            
+            if respond_to?(:signature) && signature
+              self.special_services_requested << "SIGNATURE_OPTION"
+            end
+            
+            if (respond_to?(:special_services_requested) && special_services_requested.any?)
+              b.SpecialServicesRequested do
+                if special_services_requested.any?
+                  b.SpecialServiceTypes special_services_requested.join(",")
+                end
+              
+                if signature
+                  b.SignatureOptionDetail do
+                    b.OptionType signature
+                  end
+                end
+              end
+            end
+          end
+        end
+        
+        def custom_packaging?
+          packaging_type == "YOUR_PACKAGING"
+        end
+        
+        def country_code(value)
+          Enumerations::FEDEX_COUNTRY_CODES[value.to_s] || Enumerations::RAILS_COUNTRY_CODES[value.to_s] || value.to_s
+        end
+        
+        def state_code(value)
+          Enumerations::STATE_CODES[value.to_s] || value.to_s
+        end
+    end
+  end
+end

data/lib/shippinglogic/fedex/response.rb

@@ -0,0 +1,72 @@
+require "shippinglogic/fedex/error"
+
+module Shippinglogic
+  class FedEx
+    # Methods relating to receiving a response from FedEx and cleaning it up.
+    module Response
+      SUCCESSFUL_SEVERITIES = ["SUCCESS", "NOTE", "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) && SUCCESSFUL_SEVERITIES.include?(response[:highest_severity])
+        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
+        
+        # FedEx 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)
+          if response.is_a?(Hash) && response.keys.first && response.keys.first.to_s =~ /_reply(_details)?$/
+            response.values.first
+          else
+            response
+          end
+        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
+
+        # FedEx returns a SOAP response. I just want the plain response without all of the SOAP BS.
+        # It basically turns this:
+        #
+        #   {"v3:ServiceInfo" => ...}
+        #
+        # into:
+        #
+        #   {:service_info => ...}
+        #
+        # I also did not want to use the underscore method provided by ActiveSupport because I am trying
+        # to avoid using that as a dependency.
+        def sanitize_response_key(key)
+          key.to_s.sub(/^(v[0-9]|ns):/, "").gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').gsub(/([a-z\d])([A-Z])/,'\1_\2').downcase.to_sym
+        end
+    end
+  end
+end