shippinglogic 1.2.3

data/lib/shippinglogic/fedex/service.rb

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

data/lib/shippinglogic/fedex/ship.rb

@@ -0,0 +1,238 @@
+require "base64"
+
+module Shippinglogic
+  class FedEx
+    # An interface to the shipe services provided by FedEx. Allows you to create shipments and get various information on the shipment
+    # created. Such as the tracking number, the label image, barcode image, delivery date, etc.
+    #
+    # == 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)
+    #
+    # === Label options
+    #
+    # * <tt>label_format</tt> - one of Enumerations::LABEL_FORMATS. (default: COMMON2D)
+    # * <tt>label_file_type</tt> - one of Enumerations::LABEL_FILE_TYPES. (default: PDF)
+    # * <tt>label_stock_type</tt> - one of Enumerations::LABEL_STOCK_TYPES. (default: PAPER_8.5X11_TOP_HALF_LABEL)
+    #
+    # === 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>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)
+    # * <tt>signature</tt> - one of Enumerations::SIGNATURE_OPTION_TYPES. (default: nil, which defaults to the service default)
+    #
+    # === Misc options
+    #
+    # * <tt>just_validate</tt> - will tell FedEx to ONLY validate the shipment, not actually create it. (default: false)
+    # * <tt>rate_request_types</tt> - one or more of Enumerations::RATE_REQUEST_TYPES. (default: ACCOUNT)
+    #
+    # == 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)
+    #   shipment = fedex.ship(
+    #     :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
+    #   )
+    #
+    #   shipment.inspect
+    #   #<Shippinglogic::FedEx::Ship::Shipment rate:decimal, currency:string, delivery_date:date, tracking_number:string,
+    #     label:string(base64 decoded), barcode:string(base64 decoded) >
+    #   
+    #   # to show accessor methods
+    #   shipment.tracking_number
+    #   # => "XXXXXXXXXXXXXX"
+    class Ship < Service
+      # The shipment result is an object of this class
+      class Shipment; attr_accessor :rate, :currency, :delivery_date, :tracking_number, :label, :barcode; 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
+      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
+      attribute :recipient_residential,       :boolean,     :default => false
+      
+      # label options
+      attribute :label_format,                :string,      :default => "COMMON2D"
+      attribute :label_file_type,             :string,      :default => "PDF"
+      attribute :label_stock_type,            :string,      :default => "PAPER_8.5X11_TOP_HALF_LABEL"
+      
+      # packaging options
+      attribute :packaging_type,              :string,      :default => "YOUR_PACKAGING"
+      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 { |shipment| Time.now }
+      attribute :service_type,                :string
+      attribute :dropoff_type,                :string,      :default => "REGULAR_PICKUP"
+      attribute :special_services_requested,  :array
+      attribute :signature,                   :string
+      
+      # misc options
+      attribute :just_validate,               :boolean,     :default => false
+      attribute :rate_request_types,          :array,       :default => ["ACCOUNT"]
+      
+      private
+        def target
+          @target ||= parse_response(request(build_request))
+        end
+        
+        # Just building some XML to send off to FedEx using our various options
+        def build_request
+          b = builder
+          xml = b.tag!(just_validate ? "ValidateShipmentRequest" : "ProcessShipmentRequest", :xmlns => "http://fedex.com/ws/ship/v#{VERSION[:major]}") do
+            build_authentication(b)
+            build_version(b, "ship", VERSION[:major], VERSION[:intermediate], VERSION[:minor])
+            
+            b.RequestedShipment do
+              b.ShipTimestamp ship_time.xmlschema if ship_time
+              b.DropoffType dropoff_type if dropoff_type
+              b.ServiceType service_type if service_type
+              b.PackagingType packaging_type if packaging_type
+              build_insured_value(b)
+              
+              b.Shipper do
+                build_contact(b, :shipper)
+                build_address(b, :shipper)
+              end
+              
+              b.Recipient do
+                build_contact(b, :recipient)
+                build_address(b, :recipient)
+              end
+              
+              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.LabelSpecification do
+                b.LabelFormatType label_format if label_format
+                b.ImageType label_file_type if label_file_type
+                b.LabelStockType label_stock_type if label_stock_type
+              end
+              
+              b.RateRequestTypes rate_request_types.join(",")
+              build_package(b)
+            end
+          end
+        end
+        
+        # Making sense of the reponse and grabbing the information we need.
+        def parse_response(response)
+          details = response[:completed_shipment_detail]
+          rate = details[:shipment_rating][:shipment_rate_details].first[:total_net_charge]
+          package_details = details[:completed_package_details]
+          
+          shipment = Shipment.new
+          shipment.rate = BigDecimal.new(rate[:amount])
+          shipment.currency = rate[:currency]
+          shipment.delivery_date = Date.parse(details[:routing_detail][:delivery_date])
+          shipment.tracking_number = package_details[:tracking_id][:tracking_number]
+          shipment.label = package_details[:label][:parts][:image] && Base64.decode64(package_details[:label][:parts][:image])
+          shipment.barcode = package_details[:barcodes][:common2_d_barcode] && Base64.decode64(package_details[:barcodes][:common2_d_barcode])
+          shipment
+        end
+    end
+  end
+end

data/lib/shippinglogic/fedex/signature.rb

@@ -0,0 +1,68 @@
+require "base64"
+
+module Shippinglogic
+  class FedEx
+    # An interface to the signature proof of delivery services provided by FedEx. Allows you to get an image
+    # of the signature, or you can tell fedex to fax it to a fax number.
+    #
+    # == Accessor methods / options
+    #
+    # * <tt>tracking_number</tt> - the tracking number
+    # * <tt>image_type</tt> - one of Enumerations::SIGNATURE_IMAGE_TYPES. (default: LETTER)
+    # * <tt>image_file_type</tt> - one of Enumerations::LABEL_FILE_TYPES. (default: PDF)
+    # * <tt>fax_number</tt> - if image_type is set to FAX you must provide a fax number here. (default: nil)
+    #
+    # === Simple Example
+    #
+    # Here is a very simple example:
+    #
+    #   fedex = Shippinglogic::FedEx.new(key, password, account, meter)
+    #   signature = fedex.signature(:tracking_number => "my number")
+    #
+    #   signature.inspect
+    #   # => #<Shippinglogic::FedEx::Signature::Signature image:string(base64 decoded) >
+    #   
+    #   signature.image
+    #   # => "a bunch of garble (write this to a file and save it)"
+    class Signature < Service
+      # Each tracking result is an object of this class
+      class Signature; attr_accessor :image; end
+      
+      VERSION = {:major => 3, :intermediate => 0, :minor => 0}
+      
+      attribute :image_type,      :string,  :default => "LETTER"
+      attribute :image_file_type, :string,  :default => "PDF"
+      attribute :tracking_number, :string
+      attribute :fax_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 FedEx. Notice the caching into the @target variable.
+        def target
+          @target ||= parse_response(request(build_request))
+        end
+        
+        # Just building some XML to send off to FedEx. FedEx require this particualr format.
+        def build_request
+          b = builder
+          xml = b.SignatureProofOfDeliveryRequest(:xmlns => "http://fedex.com/ws/track/v#{VERSION[:major]}") do
+            build_authentication(b)
+            build_version(b, "trck", VERSION[:major], VERSION[:intermediate], VERSION[:minor])
+            
+            b.Type image_type
+            b.TrackingNumber tracking_number
+            b.FaxDetail fax_number if fax_number
+            b.LetterFormat image_file_type
+          end
+        end
+        
+        # Grabbing the response from FedEx and making sense of it. There is a lot of unneeded information
+        # in the response.
+        def parse_response(response)
+          signature = Signature.new
+          signature.image = response[:letter] && Base64.decode64(response[:letter])
+          signature
+        end
+    end
+  end
+end

data/lib/shippinglogic/fedex/track.rb

@@ -0,0 +1,124 @@
+module Shippinglogic
+  class FedEx
+    # An interface to the track services provided by FedEx. 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:
+    #
+    #   fedex = Shippinglogic::FedEx.new(key, password, account, meter)
+    #   tracking_details = fedex.track(:tracking_number => "my number")
+    #
+    #   tracking.status
+    #   # => "Delivered"
+    #   
+    #   tracking.signature_name
+    #   # => "KKING"
+    #   
+    #   tracking.events.first
+    #   # => #<Shippinglogic::FedEx::Track::Event @postal_code="95817", @name="Delivered", @state="CA", @residential=false,
+    #   #     @city="Sacramento", @type="DL", @country="US", @occured_at=Mon Dec 08 10:43:37 -0500 2008>
+    #   
+    #   tracking.events.first.name
+    #   # => "Delivered"
+    #
+    # === Note
+    #
+    # FedEx 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
+      class Details
+        # Each tracking result is an object of this class
+        class Event; attr_accessor :name, :type, :occured_at, :city, :state, :postal_code, :country, :residential; end
+        
+        attr_accessor :origin_city,
+          :origin_state,
+          :origin_country,
+          :origin_residential,
+          :destination_city,
+          :destination_state,
+          :destination_country,
+          :destination_residential,
+          :signature_name,
+          :service_type,
+          :status,
+          :delivery_at,
+          :events
+        
+        def origin_residential?
+          origin_residential == true
+        end
+        
+        def destination_residential?
+          destination_residential == true
+        end
+        
+        def initialize(response)
+          details = response[:track_details]
+          
+          self.origin_city = details[:origin_location_address][:city]
+          self.origin_state = details[:origin_location_address][:state_or_province_code]
+          self.origin_country = details[:origin_location_address][:country_code]
+          self.origin_residential = details[:origin_location_address][:residential] == "true"
+          
+          self.destination_city = details[:destination_address][:city]
+          self.destination_state = details[:destination_address][:state_or_province_code]
+          self.destination_country = details[:destination_address][:country_code]
+          self.destination_residential = details[:destination_address][:residential] == "true"
+          
+          self.signature_name = details[:delivery_signature_name]
+          self.service_type = details[:service_type]
+          self.status = details[:status_description]
+          self.delivery_at = Time.parse(details[:actual_delivery_timestamp])
+          
+          self.events = response[:track_details][:events].collect do |details|
+            event = Event.new
+            event.name = details[:event_description]
+            event.type = details[:event_type]
+            event.occured_at = Time.parse(details[:timestamp])
+            event.city = details[:address][:city]
+            event.state = details[:address][:state_or_province_code]
+            event.postal_code = details[:address][:postal_code]
+            event.country = details[:address][:country_code]
+            event.residential = details[:address][:residential] == "true"
+            event
+          end
+        end
+      end
+      
+      VERSION = {:major => 3, :intermediate => 0, :minor => 0}
+      
+      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 FedEx. Notice the caching into the @target variable.
+        def target
+          @target ||= Details.new(request(build_request))
+        end
+        
+        # Just building some XML to send off to FedEx. FedEx require this particualr format.
+        def build_request
+          b = builder
+          xml = b.TrackRequest(:xmlns => "http://fedex.com/ws/track/v#{VERSION[:major]}") do
+            build_authentication(b)
+            build_version(b, "trck", VERSION[:major], VERSION[:intermediate], VERSION[:minor])
+            
+            b.PackageIdentifier do
+              b.Value tracking_number
+              b.Type "TRACKING_NUMBER_OR_DOORTAG"
+            end
+            
+            b.IncludeDetailedScans true
+          end
+        end
+    end
+  end
+end

data/lib/shippinglogic/proxy.rb

@@ -0,0 +1,23 @@
+module Shippinglogic
+  class Proxy
+    alias_method :real_class, :class
+    instance_methods.each do |m|
+      if (m =~ /^(__|respond_to_missing\?|real_class$|send$|object_id|respond_to\?$)/).nil?
+        undef_method(m)
+      end
+    end
+    
+    attr_accessor :target
+    
+    def initialize(target)
+      self.target = target
+    end
+    
+    protected
+      # We undefined a lot of methods at the beginning of this class. The only methods present in this
+      # class are ones that we need, everything else is delegated to our target object.
+      def method_missing(name, *args, &block)
+        target.send(name, *args, &block)
+      end
+  end
+end