shippinglogic 1.2.3

data/lib/shippinglogic/service.rb

@@ -0,0 +1,42 @@
+require "httparty"
+require "shippinglogic/proxy"
+require "shippinglogic/attributes"
+require "shippinglogic/validation"
+
+module Shippinglogic
+  class Service < Proxy
+    include Attributes
+    include HTTParty
+    include Validation
+    
+    attr_accessor :base
+    
+    # Accepts the base service object as a single parameter so that we can access
+    # authentication credentials and options.
+    def initialize(base, attributes = {})
+      self.base = base
+      super
+    end
+    
+    private
+      # Allows the cached response to be reset, specifically when an attribute changes
+      def reset_target
+        @target = nil
+      end
+      
+      # Resets the target before deferring to the +write_attribute+ method as defined by the
+      # +Attributes+ module. This keeps +Attributes+ dissociated from any proxy or service specific
+      # code, making testing simpler.
+      def write_attribute(*args)
+        reset_target
+        super
+      end
+      
+      # For each service you need to overwrite this method. This is where you make the call to the API
+      # and do your magic. See the child classes for examples on how to define this method. It is very
+      # important that you cache the result into a variable to avoid uneccessary requests.
+      def target
+        raise NotImplementedError.new("You need to implement a target method that the proxy class can delegate method calls to")
+      end
+  end
+end

data/lib/shippinglogic/ups.rb

@@ -0,0 +1,83 @@
+require "shippinglogic/ups/service"
+require "shippinglogic/ups/cancel"
+require "shippinglogic/ups/rate"
+require "shippinglogic/ups/track"
+
+module Shippinglogic
+  class UPS
+    # A hash representing default the options. If you are using this in a Rails app the best place
+    # to modify or change these options is either in an initializer or your specific environment file. Keep
+    # in mind that these options can be modified on the instance level when creating an object. See #initialize
+    # for more details.
+    #
+    # === Options
+    #
+    # * <tt>:test</tt> - this basically tells us which url to use. If set to true we will use the UPS test URL, if false we
+    #   will use the production URL. If you are using this in a rails app, unless you are in your production environment, this
+    #   will default to true automatically.
+    # * <tt>:test_url</tt> - the test URL for UPS's webservices. (default: https://wwwcie.ups.com:443/ups.app/xml)
+    # * <tt>:production_url</tt> - the production URL for UPS's webservices. (default: https://www.ups.com:443/ups.app/xml)
+    def self.options
+      @options ||= {
+        :test => !!(defined?(Rails) && !Rails.env.production?),
+        :production_url => "https://www.ups.com:443/ups.app/xml",
+        :test_url => "https://wwwcie.ups.com:443/ups.app/xml"
+      }
+    end
+
+    attr_accessor :key, :password, :account, :number, :options
+
+    # Before you can use the UPS web services you need to provide 4 credentials:
+    #
+    # 1. Your UPS access key
+    # 2. Your UPS password
+    # 3. Your UPS user ID
+    # 4. Your 6-character UPS account number
+    #
+    #TODO Explain how to acquire those 4 credentials.
+    #
+    # The last parameter allows you to modify the class options on an instance level. It accepts the
+    # same options that the class level method #options accepts. If you don't want to change any of
+    # them, don't supply this parameter.
+    def initialize(key, password, account, number, options = {})
+      self.key = key
+      self.password = password
+      self.account = account
+      self.number = number
+      self.options = self.class.options.merge(options)
+    end
+
+    # A convenience method for accessing the endpoint URL for the UPS API.
+    def url
+      options[:test] ? options[:test_url] : options[:production_url]
+    end
+
+    def cancel(attributes = {})
+      @cancel ||= Cancel.new(self, attributes)
+    end
+
+    def rate(attributes = {})
+      @rate ||= Rate.new(self, attributes)
+    end
+
+    def ship_confirm(attributes = {})
+      @ship_confirm ||= ShipConfirm.new(self, attributes)
+    end
+
+    def ship_accept(attributes = {})
+      @ship_accept ||= ShipAccept.new(self, attributes)
+    end
+
+    def ship(attributes = {})
+      @ship ||= ship_accept(:digest => ship_confirm(attributes).digest)
+    end
+
+    def track(attributes = {})
+      @track ||= Track.new(self, attributes)
+    end
+
+    def label(attributes = {})
+      @label ||= Label.new(self, attributes)
+    end
+  end
+end

data/lib/shippinglogic/ups/cancel.rb

@@ -0,0 +1,52 @@
+module Shippinglogic
+  class UPS
+    # An interface to the shipment canceling service provided by UPS. Allows you to cancel a shipment
+    #
+    # == Accessor methods / options
+    #
+    # * <tt>tracking_number</tt> - the tracking number
+    #
+    # === Simple Example
+    #
+    #   ups = Shippinglogic::UPS.new(key, password, account)
+    #   cancel = ups.cancel(:tracking_number => "my number")
+    #   cancel.perform
+    #   # => true
+    class Cancel < Service
+      def self.path
+        "/Void"
+      end
+      
+      attribute :tracking_number, :string
+      
+      # Our services are set up as a proxy. We need to access the underlying object, to trigger the request
+      # to UPS. So calling this method is a way to do that since there really is no underlying object
+      def perform
+        target && true
+      end
+      
+      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 FedEx. Notice the caching into the @target variable.
+        def target
+          @target ||= request(build_request)
+        end
+        
+        # Just building some XML to send off to FedEx. FedEx require this particualr format.
+        def build_request
+          b = builder
+          build_authentication(b)
+          b.instruct!
+          
+          b.VoidShipmentRequest do
+            b.Request do
+              b.RequestAction "1"
+            end
+            
+            #TODO Determine whether tracking numbers are valid shipment identification numbers.
+            b.ShipmentIdentificationNumber tracking_number
+          end
+        end
+    end
+  end
+end

data/lib/shippinglogic/ups/enumerations.rb

@@ -0,0 +1,56 @@
+module Shippinglogic
+  class UPS
+    # This module contains the various enumerations that UPS uses for its various options. When describing
+    # service options sometimes the docs will specify that the option must be an item in one of these arrays.
+    # You can also use these to build drop down options.
+    #
+    # Lastly, if you want to make these user friendly use a string inflector (humanize or titlize).
+    module Enumerations
+      # packaging options
+      PACKAGING_TYPES = {
+        "00" => "UNKNOWN",
+        "01" => "UPS Letter",
+        "02" => "Package",
+        "03" => "Tube",
+        "04" => "Pak",
+        "21" => "Express Box",
+        "24" => "25KG Box",
+        "25" => "10KG Box",
+        "30" => "Pallet",
+        "2a" => "Small Express Box",
+        "2b" => "Medium Express Box",
+        "2c" => "Large Express Box"
+      }
+      
+      # delivery options
+      DROPOFF_TYPES = {
+        "01" => "Daily Pickup",
+        "03" => "Customer Counter",
+        "06" => "One Time Pickup",
+        "07" => "On Call Air",
+        "11" => "Suggested Retail Rates",
+        "19" => "Letter Center",
+        "20" => "Air Service Center"
+      }
+      SERVICE_TYPES = {
+        "01" => "Next Day Air",
+        "02" => "2nd Day Air",
+        "03" => "Ground",
+        "07" => "Worldwide Express",
+        "08" => "Worldwide Expedited",
+        "11" => "Standard",
+        "12" => "3 Day Select",
+        "13" => "Next Day Air Saver",
+        "14" => "Next Day Air Early AM",
+        "54" => "Worldwide Express Plus",
+        "59" => "2nd Day Air AM",
+        "65" => "Saver",
+        "82" => "UPS Today Standard",
+        "83" => "UPS Today Dedicated Courier",
+        "84" => "UPS Today Intercity",
+        "85" => "UPS Today Express",
+        "86" => "UPS Today Express Saver"
+      }
+    end
+  end
+end

data/lib/shippinglogic/ups/error.rb

@@ -0,0 +1,42 @@
+module Shippinglogic
+  class UPS
+    # If UPS 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 UPS 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 UPS code
+    #   rescue Shippinglogic::UPS::Error => e
+    #     # do whatever you want here, just do:
+    #     # e.request
+    #     # e.response
+    #     # to get the raw response from UPS
+    #   end
+    class Error < Shippinglogic::Error
+      def initialize(request, response)
+        super
+        
+        if response.blank?
+          add_error("The response from UPS was blank.")
+        elsif !response.is_a?(Hash)
+          add_error("The response from UPS was malformed and was not in a valid XML format.")
+        elsif errors = response.fetch(:response, {})[:error]
+          errors = errors.is_a?(Array) ? errors : [errors]
+          errors.delete_if { |error| Response::SUCCESSFUL_SEVERITIES.include?(error[:error_severity]) }
+          errors.each { |error| add_error(error[:error_description], error[:error_code]) }
+        else
+          add_error(
+            "There was a problem with your UPS 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
+        
+        super(errors.collect { |error| error[:message] }.join(", "))
+      end
+    end
+  end
+end

data/lib/shippinglogic/ups/label.rb

@@ -0,0 +1,50 @@
+require "base64"
+
+module Shippinglogic
+  class UPS
+    class Label < Service
+      def self.path
+        "/LabelRecovery"
+      end
+      
+      attribute :tracking_number, :string
+      
+      private
+        def target
+          @target ||= parse_response(request(build_request))
+        end
+        
+        # Just building some XML to send off to USP using our various options
+        def build_request
+          b = builder
+          build_authentication(b)
+          b.instruct!
+          
+          b.LabelRecoveryRequest do
+            b.Request do
+              b.RequestAction "LabelRecovery"
+            end
+            
+            b.LabelSpecification do
+              b.LabelImageFormat do
+                b.Code "GIF"
+              end
+            end
+            
+            b.Translate do
+              b.LanguageCode "eng"
+              b.DialectCode "US"
+              b.Code "01"
+            end
+            
+            b.TrackingNumber tracking_number
+          end
+        end
+        
+        def parse_response(response)
+          return unless details = response.fetch(:label_results, {})[:label_image]
+          Base64.decode64(details[:graphic_image])
+        end
+    end
+  end
+end

data/lib/shippinglogic/ups/rate.rb

@@ -0,0 +1,228 @@
+module Shippinglogic
+  class UPS
+    # An interface to the rate services provided by UPS. Allows you to get an array of rates from UPS for a shipment,
+    # or a single rate for a specific service.
+    #
+    # == Options
+    # === Shipper options
+    #
+    # * <tt>shipper_name</tt> - name 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. UPS expects abbreviations, but Shippinglogic will convert full names to abbreviations for you.
+    #
+    # === Recipient options
+    #
+    # * <tt>recipient_name</tt> - name 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. UPS 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 UPS does support multiple package shipments. The problem is that all of the packages must be identical.
+    # UPS 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 UPS web services is terrible, so I could be wrong. Any tests I tried resulted in an error though.
+    #
+    # * <tt>packaging_type</tt> - one of 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 UPS will default to your account preferences)
+    # * <tt>insured_value</tt> - the value you want to insure, if any. (default: nil)
+    # * <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)
+    #
+    # === Delivery options
+    #
+    # * <tt>service_type</tt> - one of 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 DROP_OFF_TYPES. (default: REGULAR_PICKUP)
+    #
+    # === Misc options
+    #
+    # * <tt>documents_only</tt> - whether the package consists of only documents (default: false)
+    #
+    # == Simple Example
+    #
+    # Here is a very simple example. Mix and match the options above to get more accurate rates:
+    #
+    #   ups = Shippinglogic::UPS.new(key, password, account)
+    #   rates = ups.rate(
+    #     :shipper_postal_code => "10007",
+    #     :shipper_country => "US",
+    #     :recipient_postal_code => "75201",
+    #     :recipient_country_code => "US",
+    #     :package_weight => 24,
+    #     :package_length => 12,
+    #     :package_width => 12,
+    #     :package_height => 12
+    #   )
+    #
+    #   rates.first
+    #   #<Shippinglogic::UPS::Rate::Service:0x10354d108 @currency="USD", @speed=nil,
+    #     @rate=#<BigDecimal:10353ac10,'0.1885E2',18(18)>, @type="Ground", @name="Ground">
+    #   
+    #   # to show accessor methods
+    #   rates.first.name
+    #   # => "Ground"
+    class Rate < Service
+      def self.path
+        "/Rate"
+      end
+      
+      # Each rate result is an object of this class
+      class Service; attr_accessor :name, :type, :speed, :rate, :currency; end
+      
+      # shipper options
+      attribute :shipper_name,                :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
+      
+      # recipient options
+      attribute :recipient_name,              :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 => "00"
+      attribute :package_count,               :integer,     :default => 1
+      attribute :package_weight,              :float
+      attribute :package_weight_units,        :string,      :default => "LBS"
+      attribute :package_length,              :float
+      attribute :package_width,               :float
+      attribute :package_height,              :float
+      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.account }
+      
+      # delivery options
+      attribute :service_type,                :string
+      attribute :dropoff_type,                :string,      :default => "01"
+      attribute :saturday,                    :boolean,     :default => false
+      
+      # misc options
+      attribute :documents_only,              :boolean,     :default => false
+      
+      private
+        def target
+          @target ||= parse_response(request(build_request))
+        end
+        
+        def build_request
+          b = builder
+          build_authentication(b)
+          b.instruct!
+          
+          b.RatingServiceSelectionRequest do
+            b.Request do
+              b.RequestAction "Rate"
+              b.RequestOption service_type ? "Rate" : "Shop"
+            end
+            
+            b.PickupType do
+              b.Code dropoff_type
+            end
+            
+            b.Shipment do
+              b.Shipper do
+                b.Name shipper_name
+                b.ShipperNumber payor_account_number
+                build_address(b, :shipper)
+              end
+              
+              b.ShipTo do
+                b.CompanyName recipient_name
+                build_address(b, :recipient)
+              end
+              
+              if service_type
+                b.Service do
+                  b.Code service_type
+                end
+              end
+              
+              b.DocumentsOnly if documents_only
+              
+              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
+              
+              b.ShipmentServiceOptions do
+                b.SaturdayDelivery if saturday
+              end
+            end
+          end
+        end
+        
+        def parse_response(response)
+          return [] if !response[:rated_shipment]
+          
+          response[:rated_shipment].collect do |details|
+            service = Service.new
+            service.name = Enumerations::SERVICE_TYPES[details[:service][:code]]
+            service.type = service.name
+            service.speed = (days = details[:guaranteed_days_to_delivery]) && (days.to_i * 86400)
+            service.rate = BigDecimal.new(details[:total_charges][:monetary_value])
+            service.currency = details[:total_charges][:currency_code]
+            service
+          end
+        end
+    end
+  end
+end