fedex 2.0.1 → 2.2.0

data/.gitignore

@@ -8,4 +8,7 @@ doc/*
 pkg/*
 .yardopts
 fedex_credentials.yml
-spec/vcr
+spec/vcr
+*.bbprojectd
+.DS_Store
+hacks

data/Readme.md

@@ -116,7 +116,7 @@ Fedex provides multiple total values; `total_net_charge` is the final amount you
           @rate_zone="51">
 ```
 
-### ** Generate a shipping label(PDF) **
+### ** Generate a shipping label (PDF) **
 
 To create a label for a shipment:
 
@@ -129,8 +129,84 @@ label = fedex.label(:filename => "my_dir/example.pdf",
                     :shipping_details => shipping_details)
 ```
 
-The label will be saved to the file system as the filename you specify and is Adobe PDF format.
-Note that you can currently print a label for a single package at a time.
+### ** Generate a shipping label in any available format **
+
+Change the filename extension and pass a label_specification hash. For example:
+
+```ruby
+example_spec = {
+  :image_type => "EPL2",
+  :label_stock_type => "STOCK_4X6"
+}
+
+label = fedex.label(:filename => "my_dir/example_epl2.pcx",
+                    :shipper=>shipper,
+                    :recipient => recipient,
+                    :packages => packages,
+                    :service_type => "FEDEX_GROUND",
+                    :shipping_details => shipping_details,
+                    :label_specification => example_spec)
+```
+
+### ** Tracking a shipment **
+
+To track a shipment:
+
+```ruby
+tracking_info = fedex.track(:tracking_number => "1234567890123")
+
+tracking_info.tracking_number
+# => "1234567890123"
+
+tracking_info.status
+# => "Delivered"
+
+tracking_info.events.first.description
+# => "On FedEx vehicle for delivery"
+```
+
+### ** Tracking a shipment **
+
+To track a shipment:
+
+```ruby
+tracking_info = fedex.track(:tracking_number => "1234567890123")
+
+tracking_info.tracking_number
+# => "1234567890123"
+
+tracking_info.status
+# => "Delivered"
+
+tracking_info.events.first.description
+# => "On FedEx vehicle for delivery"
+```
+
+### ** Verifying an address **
+
+To verify an address is valid and deliverable:
+
+```ruby
+
+address = {
+  :street      => "5 Elm Street",
+  :city        => "Norwalk",
+  :state       => "CT",
+  :postal_code => "06850",
+  :country     => "USA"
+}
+
+address_result = fedex.validate_address(:address => address)
+
+address_result.residential
+# => true
+
+address_result.score
+# => 100
+
+address_result.postal_code
+# => "06850-3901"
+```
 
 # Services/Options Available
 
@@ -143,6 +219,8 @@ Fedex::Shipment::DROP_OFF_TYPES
 # Contributors:
 - [jazminschroeder](http://github.com/jazminschroeder) (Jazmin Schroeder)
 - [parndt](https://github.com/parndt) (Philip Arndt)
+- [mmell](https://github.com/mmell) (Michael Mell)
+- [jordanbyron](https://github.com/jordanbyron) (Jordan Byron)
 
 # Copyright/License:
 Copyright 2011 [Jazmin Schroeder](http://jazminschroeder.com)

data/fedex.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Jazmin Schroeder"]
   s.email       = ["jazminschroeder@gmail.com"]
   s.homepage    = "https://github.com/jazminschroeder/fedex"
-  s.summary     = %q{Fedex Rate Webservice}
-  s.description = %q{Ruby Library to use Fedex Web Services(version 10)}
+  s.summary     = %q{Fedex Web Services}
+  s.description = %q{Provides an interface to Fedex Web Services(version 10) - shipping rates, generate labels and address validation}
 
   s.rubyforge_project = "fedex"
 

data/lib/fedex/address.rb

@@ -0,0 +1,30 @@
+module Fedex
+  class Address
+
+    attr_reader :changes, :score, :confirmed, :available, :status, :residential,
+                :business, :street_lines, :city, :state, :province_code,
+                :postal_code, :country_code
+
+    def initialize(options)
+      @changes   = options[:changes]
+      @score     = options[:score].to_i
+      @confirmed = options[:delivery_point_validation] == "CONFIRMED"
+      @available = options[:delivery_point_validation] != "UNAVAILABLE"
+
+      @status      = options[:residential_status]
+      @residential = status == "RESIDENTIAL"
+      @business    = status == "BUSINESS"
+
+      address        = options[:address]
+
+      @street_lines  = address[:street_lines]
+      @city          = address[:city]
+      @state         = address[:state_or_province_code]
+      @province_code = address[:state_or_province_code]
+      @postal_code   = address[:postal_code]
+      @country_code  = address[:country_code]
+
+      @options = options
+    end
+  end
+end

data/lib/fedex/helpers.rb

@@ -2,9 +2,10 @@ module Fedex
   module Helpers
 
     private
-    # String to CamelCase
-    def camelize(str)
-      str.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+    # String or :symbol to CamelCase
+    def camelize(s)
+      # s.to_s.split('_').map { |e| e.capitalize }.join('')
+      s.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
     end
 
     # Helper method to validate required fields
@@ -16,4 +17,4 @@ module Fedex
       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
     end
   end
-end
+end

data/lib/fedex/label.rb

@@ -1,11 +1,52 @@
+require 'base64'
+require 'pathname'
+
 module Fedex
   class Label
-    attr_accessor :options
+    attr_accessor :options, :image, :response_details
 
     # Initialize Fedex::Label Object
     # @param [Hash] options
-    def initialize(options = {})
-      @options = options
+    def initialize(label_details = {})
+      @response_details = label_details[:process_shipment_reply]
+      package_details = label_details[:process_shipment_reply][:completed_shipment_detail][:completed_package_details]
+      @options = package_details[:label]
+      @options[:format] = label_details[:format]
+      @options[:tracking_number] = package_details[:tracking_ids][:tracking_number]
+      @options[:file_name] = label_details[:file_name]
+      
+      @image = Base64.decode64(options[:parts][:image]) if has_image?
+
+      if file_name = @options[:file_name]
+        save(file_name, false)
+      end
+    end
+
+    def name
+      [tracking_number, format].join('.')
+    end
+
+    def format
+      options[:format]
+    end
+
+    def tracking_number
+      options[:tracking_number]
+    end
+
+    def has_image?
+      options[:parts] && options[:parts][:image]
+    end
+
+    def save(path, append_name = true)
+      return unless has_image?
+
+      full_path = Pathname.new(path)
+      full_path = full_path.join(name) if append_name
+
+      File.open(full_path, 'wb') do|f|
+        f.write(@image)
+      end
     end
   end
 end

data/lib/fedex/request/address.rb

@@ -0,0 +1,92 @@
+require 'fedex/request/base'
+require 'fedex/address'
+require 'fileutils'
+
+module Fedex
+  module Request
+    class Address < Base
+      def initialize(credentials, options={})
+        requires!(options, :address)
+        @credentials = credentials
+        @address     = options[:address]
+      end
+
+      def process_request
+        api_response = self.class.post(api_url, :body => build_xml)
+        puts api_response if @debug == true
+        response = parse_response(api_response)
+        if success?(response)
+          options = response[:address_validation_reply][:address_results][:proposed_address_details]
+
+          Fedex::Address.new(options)
+        else
+          error_message = if response[:address_validation_reply]
+            [response[:address_validation_reply][:notifications]].flatten.first[:message]
+          else
+            api_response["Fault"]["detail"]["fault"]["reason"]
+          end rescue $1
+          raise RateError, error_message
+        end
+      end
+
+      private
+
+      # Build xml Fedex Web Service request
+      def build_xml
+        builder = Nokogiri::XML::Builder.new do |xml|
+          xml.AddressValidationRequest(:xmlns => "http://fedex.com/ws/addressvalidation/v2"){
+            add_web_authentication_detail(xml)
+            add_client_detail(xml)
+            add_version(xml)
+            add_request_timestamp(xml)
+            add_address_validation_options(xml)
+            add_address_to_validate(xml)
+          }
+        end
+        builder.doc.root.to_xml
+      end
+
+      def add_request_timestamp(xml)
+        timestamp = Time.now
+
+        # Calculate current timezone offset manually.
+        # Ruby <= 1.9.2 does not support this in Time#strftime
+        #
+        utc_offest = "#{timestamp.gmt_offset < 0 ? "-" : "+"}%02d:%02d" %
+                     (timestamp.gmt_offset / 60).abs.divmod(60)
+        timestamp  = timestamp.strftime("%Y-%m-%dT%H:%M:%S") + utc_offest
+
+        xml.RequestTimestamp timestamp
+      end
+
+      def add_address_validation_options(xml)
+        xml.Options{
+          xml.CheckResidentialStatus true
+        }
+      end
+
+      def add_address_to_validate(xml)
+        xml.AddressesToValidate{
+          xml.Address{
+            xml.StreetLines         @address[:street]
+            xml.City                @address[:city]
+            xml.StateOrProvinceCode @address[:state]
+            xml.PostalCode          @address[:postal_code]
+            xml.CountryCode         @address[:country]
+          }
+        }
+      end
+
+      def service
+        { :id => 'aval', :version => 2 }
+      end
+
+      # Successful request
+      def success?(response)
+        response[:address_validation_reply] &&
+          %w{SUCCESS WARNING NOTE}.include?(response[:address_validation_reply][:highest_severity])
+      end
+
+    end
+  end
+end

data/lib/fedex/request/base.rb

@@ -17,9 +17,6 @@ module Fedex
       # Fedex Production URL
       PRODUCTION_URL = "https://gateway.fedex.com:443/xml/"
 
-      # Fedex Version number for the Fedex service used
-      VERSION = 10
-
       # List of available Service Types
       SERVICE_TYPES = %w(EUROPE_FIRST_INTERNATIONAL_PRIORITY FEDEX_1_DAY_FREIGHT FEDEX_2_DAY FEDEX_2_DAY_AM FEDEX_2_DAY_FREIGHT FEDEX_3_DAY_FREIGHT FEDEX_EXPRESS_SAVER FEDEX_FIRST_FREIGHT FEDEX_FREIGHT_ECONOMY FEDEX_FREIGHT_PRIORITY FEDEX_GROUND FIRST_OVERNIGHT GROUND_HOME_DELIVERY INTERNATIONAL_ECONOMY INTERNATIONAL_ECONOMY_FREIGHT INTERNATIONAL_FIRST INTERNATIONAL_PRIORITY INTERNATIONAL_PRIORITY_FREIGHT PRIORITY_OVERNIGHT SMART_POST STANDARD_OVERNIGHT)
 
@@ -48,6 +45,7 @@ module Fedex
         requires!(options, :shipper, :recipient, :packages, :service_type)
         @credentials = credentials
         @shipper, @recipient, @packages, @service_type, @customs_clearance, @debug = options[:shipper], options[:recipient], options[:packages], options[:service_type], options[:customs_clearance], options[:debug]
+        @debug = ENV['DEBUG'] == 'true'
         @shipping_options =  options[:shipping_options] ||={}
       end
 
@@ -73,14 +71,18 @@ module Fedex
         xml.ClientDetail{
           xml.AccountNumber @credentials.account_number
           xml.MeterNumber @credentials.meter
+          xml.Localization{
+            xml.LanguageCode 'en' # English
+            xml.LocaleCode   'us' # United States
+          }
         }
       end
 
       # Add Version to xml request, using the latest version V10 Sept/2011
       def add_version(xml)
         xml.Version{
-          xml.ServiceId service_id
-          xml.Major VERSION
+          xml.ServiceId service[:id]
+          xml.Major     service[:version]
           xml.Intermediate 0
           xml.Minor 0
         }
@@ -164,12 +166,22 @@ module Fedex
               xml.Units package[:weight][:units]
               xml.Value package[:weight][:value]
             }
-            xml.Dimensions{
-              xml.Length package[:dimensions][:length]
-              xml.Width package[:dimensions][:width]
-              xml.Height package[:dimensions][:height]
-              xml.Units package[:dimensions][:units]
-            }
+            if package[:dimensions]
+              xml.Dimensions{
+                xml.Length package[:dimensions][:length]
+                xml.Width package[:dimensions][:width]
+                xml.Height package[:dimensions][:height]
+                xml.Units package[:dimensions][:units]
+              }
+            end
+            if package[:customer_refrences]
+              xml.CustomerReferences{
+              package[:customer_refrences].each do |value|
+                 xml.CustomerReferenceType 'CUSTOMER_REFERENCE'
+                 xml.Value                 value
+              end
+              }
+            end
           }
         end
       end
@@ -177,7 +189,7 @@ module Fedex
       # Add customs clearance(for international shipments)
       def add_customs_clearance(xml)
         xml.CustomsClearanceDetail{
-          customs_to_xml(xml, @customs_clearance)
+          hash_to_xml(xml, @customs_clearance)
         }
       end
 
@@ -192,22 +204,22 @@ module Fedex
         raise NotImplementedError, "Override build_xml in subclass"
       end
 
-      # Build nodes dinamically from the provided customs clearance hash
-      def customs_to_xml(xml, hash)
+      # Build xml nodes dynamically from the hash keys and values
+      def hash_to_xml(xml, hash)
         hash.each do |key, value|
+          element = camelize(key)
           if value.is_a?(Hash)
-            xml.send "#{camelize(key.to_s)}" do |x|
-              customs_to_xml(x, value)
+            xml.send element do |x|
+              hash_to_xml(x, value)
             end
           elsif value.is_a?(Array)
-            node = key
             value.each do |v|
-              xml.send "#{camelize(node.to_s)}" do |x|
-                customs_to_xml(x, v)
-              end
-            end
+              xml.send element do |x|
+                hash_to_xml(x, v)
+              end  
+            end  
           else
-            xml.send "#{camelize(key.to_s)}", value unless key.is_a?(Hash)
+            xml.send element, value
           end
         end
       end
@@ -217,7 +229,7 @@ module Fedex
         response = sanitize_response_keys(response)
       end
 
-      # Recursively sanitizes the response object by clenaing up any hash keys.
+      # Recursively sanitizes the response object by cleaning up any hash keys.
       def sanitize_response_keys(response)
         if response.is_a?(Hash)
           response.inject({}) { |result, (key, value)| result[underscorize(key).to_sym] = sanitize_response_keys(value); result }
@@ -228,8 +240,9 @@ module Fedex
         end
       end
 
-      def service_id
-        'crs'
+      def service
+        raise NotImplementedError,
+          "Override service in subclass: {:id => 'service', :version => 1}"
       end
 
       # Use GROUND_HOME_DELIVERY for shipments going to a residential address within the US.
@@ -248,4 +261,4 @@ module Fedex
 
     end
   end
-end
+end