fedex 2.0.1 → 2.2.0

data/lib/fedex/request/label.rb

@@ -1,94 +1,29 @@
 require 'fedex/request/base'
 require 'fedex/label'
+require 'fedex/request/shipment'
 require 'fileutils'
 
 module Fedex
   module Request
-    class Label < Base
+    class Label < Shipment
       def initialize(credentials, options={})
         super(credentials, options)
-        requires!(options, :filename)
         @filename = options[:filename]
       end
 
-      # Sends post request to Fedex web service and parse the response.
-      # A Fedex::Label object is created if the response is successful and
-      # a PDF file is created with the label at the specified location.
-      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)
-          label_details = response[:process_shipment_reply][:completed_shipment_detail][:completed_package_details][:label]
-
-          create_pdf(label_details)
-          Fedex::Label.new(label_details)
-        else
-          error_message = if response[:process_shipment_reply]
-            [response[:process_shipment_reply][:notifications]].flatten.first[:message]
-          else
-            api_response["Fault"]["detail"]["fault"]["reason"]
-          end rescue $1
-          raise RateError, error_message
-        end
-      end
-
       private
 
-      # Add information for shipments
-      def add_requested_shipment(xml)
-        xml.RequestedShipment{
-          xml.ShipTimestamp Time.now.utc.iso8601(2)
-          xml.DropoffType @shipping_options[:drop_off_type] ||= "REGULAR_PICKUP"
-          xml.ServiceType service_type
-          xml.PackagingType @shipping_options[:packaging_type] ||= "YOUR_PACKAGING"
-          add_shipper(xml)
-          add_recipient(xml)
-          add_shipping_charges_payment(xml)
-          add_customs_clearance(xml) if @customs_clearance
-          xml.LabelSpecification {
-            xml.LabelFormatType "COMMON2D"
-            xml.ImageType "PDF"
-          }
-          xml.RateRequestTypes "ACCOUNT"
-          add_packages(xml)
-        }
-      end
+      def success_response(api_response, response)
+        super
 
-      # Build xml Fedex Web Service request
-      def build_xml
-        builder = Nokogiri::XML::Builder.new do |xml|
-          xml.ProcessShipmentRequest(:xmlns => "http://fedex.com/ws/ship/v10"){
-            add_web_authentication_detail(xml)
-            add_client_detail(xml)
-            add_version(xml)
-            add_requested_shipment(xml)
-          }
-        end
-        builder.doc.root.to_xml
-      end
-
-      def create_pdf(label_details)
-        [label_details[:parts]].flatten.each do |part|
-          if image = (Base64.decode64(part[:image]) if part[:image])
-            FileUtils.mkdir_p File.dirname(@filename)
-            File.open(@filename, 'w') do |file|
-              file.write image
-            end
-          end
-        end
-      end
-
-      def service_id
-        'ship'
-      end
+        label_details = response.merge!({
+          :format => @label_specification[:image_type],
+          :file_name => @filename
+        })
 
-      # Successful request
-      def success?(response)
-        response[:process_shipment_reply] &&
-          %w{SUCCESS WARNING NOTE}.include?(response[:process_shipment_reply][:highest_severity])
+        Fedex::Label.new label_details
       end
 
     end
   end
-end
+end

data/lib/fedex/request/rate.rb

@@ -6,7 +6,7 @@ module Fedex
       # Sends post request to Fedex web service and parse the response, a Rate object is created if the response is successful
       def process_request
         api_response = self.class.post(api_url, :body => build_xml)
-        puts api_response if @debug == true
+        puts api_response if @debug
         response = parse_response(api_response)
         if success?(response)
           rate_details = [response[:rate_reply][:rate_reply_details][:rated_shipment_details]].flatten.first[:shipment_rate_detail]
@@ -51,8 +51,8 @@ module Fedex
         builder.doc.root.to_xml
       end
 
-      def service_id
-        'crs'
+      def service
+        { :id => 'crs', :version => 10 }
       end
 
       # Successful request

data/lib/fedex/request/shipment.rb

@@ -0,0 +1,106 @@
+require 'fedex/request/base'
+
+module Fedex
+  module Request
+    class Shipment < Base
+      attr_reader :response_details
+
+      def initialize(credentials, options={})
+        super
+        requires! options
+        # Label specification is required even if we're not using it.
+        @label_specification = {
+          :label_format_type => 'COMMON2D',
+          :image_type => 'PDF',
+          :label_stock_type => 'PAPER_LETTER'
+        }
+        @label_specification.merge! options[:label_specification] if options[:label_specification]
+      end
+
+      # Sends post request to Fedex web service and parse the response.
+      # A label file is created with the label at the specified location.
+      # The parsed Fedex response is available in #response_details
+      # e.g. response_details[:completed_shipment_detail][:completed_package_details][:tracking_ids][:tracking_number]
+      def process_request
+        api_response = self.class.post api_url, :body => build_xml
+        puts api_response if @debug
+        response = parse_response(api_response)
+        if success?(response)
+          success_response(api_response, response)
+        else
+          failure_response(api_response, response)
+        end
+      end
+
+      private
+
+      # Add information for shipments
+      def add_requested_shipment(xml)
+        xml.RequestedShipment{
+          xml.ShipTimestamp Time.now.utc.iso8601(2)
+          xml.DropoffType @shipping_options[:drop_off_type] ||= "REGULAR_PICKUP"
+          xml.ServiceType service_type
+          xml.PackagingType @shipping_options[:packaging_type] ||= "YOUR_PACKAGING"
+          add_shipper(xml)
+          add_recipient(xml)
+          add_shipping_charges_payment(xml)
+          add_customs_clearance(xml) if @customs_clearance
+          add_custom_components(xml)
+          xml.RateRequestTypes "ACCOUNT"
+          add_packages(xml)
+        }
+      end
+
+      # Hook that can be used to add custom parts.
+      def add_custom_components(xml)
+        add_label_specification xml
+      end
+
+      # Add the label specification
+      def add_label_specification(xml)
+        xml.LabelSpecification {
+          hash_to_xml(xml, @label_specification)
+        }
+      end
+
+      # Callback used after a failed shipment response.
+      def failure_response(api_response, response)
+        error_message = if response[:process_shipment_reply]
+          [response[:process_shipment_reply][:notifications]].flatten.first[:message]
+        else
+          api_response["Fault"]["detail"]["fault"]["reason"]
+        end rescue $1
+        raise RateError, error_message
+      end
+
+      # Callback used after a successful shipment response.
+      def success_response(api_response, response)
+        @response_details = response[:process_shipment_reply]
+      end
+
+      # Build xml Fedex Web Service request
+      def build_xml
+        builder = Nokogiri::XML::Builder.new do |xml|
+          xml.ProcessShipmentRequest(:xmlns => "http://fedex.com/ws/ship/v10"){
+            add_web_authentication_detail(xml)
+            add_client_detail(xml)
+            add_version(xml)
+            add_requested_shipment(xml)
+          }
+        end
+        builder.doc.root.to_xml
+      end
+
+      def service
+        { :id => 'ship', :version => 10 }
+      end
+
+      # Successful request
+      def success?(response)
+        response[:process_shipment_reply] &&
+          %w{SUCCESS WARNING NOTE}.include?(response[:process_shipment_reply][:highest_severity])
+      end
+
+    end
+  end
+end

data/lib/fedex/request/tracking_information.rb

@@ -0,0 +1,89 @@
+require 'fedex/request/base'
+require 'fedex/tracking_information'
+
+module Fedex
+  module Request
+    class TrackingInformation < Base
+
+      attr_reader :package_type, :package_id
+
+      def initialize(credentials, options={})
+        requires!(options, :package_type, :package_id) unless options.has_key?(:tracking_number)
+
+        @package_id   = options[:package_id]   || options.delete(:tracking_number)
+        @package_type = options[:package_type] || "TRACKING_NUMBER_OR_DOORTAG"
+        @credentials  = credentials
+
+        # Optional
+        @include_detailed_scans = options[:include_detailed_scans]
+        @uuid                   = options[:uuid]
+        @paging_token           = options[:paging_token]
+
+        unless package_type_valid?
+          raise "Unknown package type '#{package_type}'"
+        end
+      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[:track_reply][:track_details]
+
+          Fedex::TrackingInformation.new(options)
+        else
+          error_message = if response[:track_reply]
+            response[:track_reply][:notifications][: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.TrackRequest(:xmlns => "http://fedex.com/ws/track/v#{service[:version]}"){
+            add_web_authentication_detail(xml)
+            add_client_detail(xml)
+            add_version(xml)
+            add_package_identifier(xml)
+            xml.IncludeDetailedScans @include_detailed_scans
+
+            # Optional
+            xml.TrackingNumberUniqueIdentifier @uuid if @uuid
+            xml.PagingToken @paging_token            if @paging_token
+          }
+        end
+        builder.doc.root.to_xml
+      end
+
+      def service
+        { :id => 'trck', :version => 5 }
+      end
+
+      def add_package_identifier(xml)
+        xml.PackageIdentifier{
+          xml.Value package_id
+          xml.Type  package_type
+        }
+      end
+
+      # Successful request
+      def success?(response)
+        response[:track_reply] &&
+          %w{SUCCESS WARNING NOTE}.include?(response[:track_reply][:highest_severity])
+      end
+
+      def package_type_valid?
+        Fedex::TrackingInformation::PACKAGE_IDENTIFIER_TYPES.include? package_type
+      end
+
+    end
+  end
+end

data/lib/fedex/shipment.rb

@@ -1,6 +1,8 @@
 require 'fedex/credentials'
 require 'fedex/request/label'
 require 'fedex/request/rate'
+require 'fedex/request/tracking_information'
+require 'fedex/request/address'
 
 module Fedex
   class Shipment
@@ -23,6 +25,7 @@ module Fedex
     # @param [Array] packages, An arrary including a hash for each package being shipped
     # @param [String] service_type, A valid fedex service type, to view a complete list of services Fedex::Shipment::SERVICE_TYPES
     # @param [String] filename, A location where the label will be saved
+    # @param [Hash] label_specification, A hash containing the label printer settings
     def label(options = {})
       Request::Label.new(@credentials, options).process_request
     end
@@ -35,5 +38,24 @@ module Fedex
       Request::Rate.new(@credentials, options).process_request
     end
 
+    # @param [Hash] address, A hash containing the address information
+    def validate_address(options = {})
+      Request::Address.new(@credentials, options).process_request
+    end
+
+    # @param [Hash] shipper, A hash containing the shipper information
+    # @param [Hash] recipient, A hash containing the recipient information
+    # @param [Array] packages, An arrary including a hash for each package being shipped
+    # @param [String] service_type, A valid fedex service type, to view a complete list of services Fedex::Shipment::SERVICE_TYPES
+    def ship(options = {})
+      Request::Shipment.new(@credentials, options).process_request
+    end
+
+    # @param [Hash] package_id, A string with the requested tracking number
+    # @param [Hash] package_type, A string identifitying the type of tracking number used. Full list Fedex::Track::PACKAGE_IDENTIFIER_TYPES
+    def track(options = {})
+      Request::TrackingInformation.new(@credentials, options).process_request
+    end
+
   end
-end
+end

data/lib/fedex/tracking_information.rb

@@ -0,0 +1,49 @@
+require 'fedex/tracking_information/event'
+
+module Fedex
+  class TrackingInformation
+    PACKAGE_IDENTIFIER_TYPES = %w{
+      BILL_OF_LADING
+      COD_RETURN_TRACKING_NUMBER
+      CUSTOMER_AUTHORIZATION_NUMBER
+      CUSTOMER_REFERENCE
+      DEPARTMENT
+      FREE_FORM_REFERENCE
+      GROUND_INTERNATIONAL
+      GROUND_SHIPMENT_ID
+      GROUP_MPS
+      INVOICE
+      JOB_GLOBAL_TRACKING_NUMBER
+      ORDER_GLOBAL_TRACKING_NUMBER
+      ORDER_TO_PAY_NUMBER
+      PARTNER_CARRIER_NUMBER
+      PART_NUMBER
+      PURCHASE_ORDER
+      RETURN_MATERIALS_AUTHORIZATION
+      RETURNED_TO_SHIPPER_TRACKING_NUMBER
+      TRACKING_CONTROL_NUMBER
+      TRACKING_NUMBER_OR_DOORTAG
+      TRANSPORTATION_CONTROL_NUMBER
+      SHIPPER_REFERENCE
+      STANDARD_MPS
+    }
+
+    attr_reader :tracking_number, :signature_name, :service_type, :status,
+                :delivery_at, :events
+
+    def initialize(details = {})
+      @details = details
+
+      @tracking_number = details[:tracking_number]
+      @signature_name  = details[:delivery_signature_name]
+      @service_type    = details[:service_type]
+      @status          = details[:status_description]
+      @delivery_at     = Time.parse(details[:actual_delivery_timestamp])
+
+      @events = details[:events].map do |event_details|
+        Event.new(event_details)
+      end
+    end
+
+  end
+end

data/lib/fedex/tracking_information/event.rb

@@ -0,0 +1,19 @@
+module Fedex
+  class TrackingInformation
+    class Event
+      attr_reader :description, :type, :occured_at, :city, :state, :postal_code,
+                  :country, :residential
+
+      def initialize(details = {})
+        @description  = details[:event_description]
+        @type         = details[:event_type]
+        @occured_at   = Time.parse(details[:timestamp])
+        @city         = details[:address][:city]
+        @state        = details[:address][:state_or_province_code]
+        @postal_code  = details[:address][:postal_code]
+        @country      = details[:address][:country_code]
+        @residential  = details[:address][:residential] == "true"
+      end
+    end
+  end
+end

data/lib/fedex/version.rb

@@ -1,3 +1,3 @@
 module Fedex
-  VERSION = "2.0.1" 
+  VERSION = "2.2.0"
 end

data/spec/lib/fedex/address_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+module Fedex
+  describe Address, :production do
+    describe "validation" do
+
+      # Address Validation is only enabled in the production environment
+      #
+      let(:fedex) { Shipment.new(fedex_production_credentials) }
+
+      context "valid address", :vcr do
+        let(:address) do
+          {
+            :street      => "5 Elm Street",
+            :city        => "Norwalk",
+            :state       => "CT",
+            :postal_code => "06850",
+            :country     => "USA"
+          }
+        end
+
+        let(:options) do
+          { :address => address }
+        end
+
+        it "validates the address" do
+          address = fedex.validate_address(options)
+
+          address.residential.should be_true
+          address.business.should    be_false
+          address.score.should ==    100
+
+          address.postal_code.should == "06850-3901"
+        end
+      end
+
+    end
+  end
+end