simple_shipping 0.4.6

data/lib/simple_shipping/demo/fedex.rb

@@ -0,0 +1,46 @@
+# Helper object to send demo requests to FedEx in order to test credentials
+# and the library.
+#
+# @example
+#   demo     = SimpleShipping::Demo::Fedex.new(credentials)
+#   response = demo.shipment_request
+class SimpleShipping::Demo::Fedex < SimpleShipping::Demo::Base
+  attr_reader :credentials
+
+  def initialize(options = {})
+    @options = options.reverse_merge(:log => false)
+  end
+
+  # Build the package object.
+  #
+  # @return [SimpleShipping::Package]
+  def package
+    @package ||= SimpleShipping::Package.new(
+        :weight          => 1,
+        :length          => 2,
+        :height          => 3,
+        :dimension_units => :in,  # you can use :kg as well
+        :weight_units    => :lb,  # you can use :cm as well
+        :width           => 4,
+        :packaging_type  => :your
+    )
+  end
+
+  # Initialize the FedEx client.
+  #
+  # @return [SimpleShipping::Fedex::Client]
+  def fedex_client
+    @fedex_client ||= SimpleShipping::Fedex::Client.new(
+        :credentials => options.slice(:key, :password, :account_number, :meter_number),
+        :log         => options[:log],
+        :live        => options[:live]
+    )
+  end
+
+  # Send the shipment request to FedEx.
+  #
+  # @return [SimpleShipping::Fedex::Response]
+  def shipment_request
+    fedex_client.shipment_request(shipper, recipient, package)
+  end
+end

data/lib/simple_shipping/demo/ups.rb

@@ -0,0 +1,68 @@
+# Helper object to send demo requests to UPS in order to test credentials
+# and the library.
+#
+# @example
+#   demo = SimpleShipping::Demo::Ups.new(credentials)
+#   response = demo.shipment_request
+class SimpleShipping::Demo::Ups < SimpleShipping::Demo::Base
+  attr_reader :credentials
+
+  def initialize(options = {})
+    @options = options.reverse_merge(
+        :log          => false,
+        :service_type => :second_day_air
+    )
+  end
+
+  # Build the package object.
+  #
+  # @return [SimpleShipping::Package]
+  def package
+    @package ||= SimpleShipping::Package.new(
+        :weight         => 0.5,
+        :packaging_type => :envelope
+    )
+  end
+
+  # Initialize the UPS client for shipment requests.
+  #
+  # @return [SimpleShipping::Ups::ShipClient]
+  def ship_client
+    @ship_client ||= SimpleShipping::Ups::ShipClient.new(
+        :credentials => options.slice(:username, :password, :access_license_number),
+        :log         => options[:log]
+    )
+  end
+
+  # Initialize the UPS client for void requests.
+  #
+  # @return [SimpleShipping::Ups::VoidClient]
+  def void_client
+    @void_client ||= SimpleShipping::Ups::VoidClient.new(
+        :credentials => options.slice(:username, :password, :access_license_number),
+        :log         => options[:log],
+        :live        => options[:live]
+    )
+  end
+
+  # Shipment Id. The number is picked randomly.
+  #
+  # @return [String]
+  def shipment_identification_number
+    @shipment_identification_number ||= '1234567890'
+  end
+
+  # Send a shipment request.
+  #
+  # @return [ShipClient::Ups::ShipmentResponse]
+  def shipment_request
+    ship_client.shipment_request(shipper, recipient, package, :service_type => options[:service_type])
+  end
+
+  # Send a request to void a shipment.
+  #
+  # @return [ShipClient::Ups::VoidResponse]
+  def void_request
+    void_client.void_request(shipment_identification_number)
+  end
+end

data/lib/simple_shipping/exceptions.rb

@@ -0,0 +1,40 @@
+module SimpleShipping
+  # Parent error for all SimpleShipping errors.
+  class Error < StandardError; end
+
+  # Error raises when response does not contain a label.
+  class NoLabelError < Error ; end
+
+  # Raises when some data is invalid or missing to build a request.
+  class ValidationError < Error
+    # @param model_or_msg [Abstract::Model, String]
+    def initialize(model_or_msg)
+      @message = case model_or_msg
+      when Abstract::Model
+        "Invalid model #{model_or_msg.class}. Validation errors: #{model_or_msg.errors.full_messages.join(', ')}"
+      when String
+        model_or_msg
+      end
+
+      super(@message)
+    end
+  end
+
+  # Raised when a remote request fails.
+  class RequestError < Error
+    # @param [Savon::SOAPFault] savon_fault Savon exception
+    def initialize(savon_fault)
+      fault = savon_fault.to_hash[:fault]
+
+      @message =
+        if fault[:faultcode] # SOAP 1.1 fault.
+          detail = fault[:detail][:errors][:error_detail][:primary_error_code]
+          "#{fault[:faultstring]} (#{detail[:code]}) #{detail[:description]}"
+        elsif fault[:code] # SOAP 1.2 fault.
+          "(#{fault[:code][:value]}) #{fault[:reason][:text]}"
+        end
+
+      super(@message)
+    end
+  end
+end

data/lib/simple_shipping/fedex.rb

@@ -0,0 +1,14 @@
+# Namespace for FedEx provider.
+module SimpleShipping::Fedex
+  extend ActiveSupport::Autoload
+
+  autoload :Client
+  autoload :Request
+  autoload :Response
+  autoload :ShipmentBuilder
+  autoload :PackageBuilder
+  autoload :PartyBuilder
+
+  autoload :ShipmentRequest
+  autoload :ShipmentResponse
+end

data/lib/simple_shipping/fedex/client.rb

@@ -0,0 +1,41 @@
+module SimpleShipping::Fedex
+  # Required credentials:
+  # * _key_
+  # * _password_
+  # * _account_number_
+  # * _meter_number_
+  #
+  # = Usage
+  #  client = SimpleShipping::Fedex::Client.new(:key            => "KEY",
+  #                                             :password       => "PASSWORD",
+  #                                             :account_number => "ACCOUNT NUMBER",
+  #                                             :METER_NUMBER   => "METER NUMBER")
+  #  client.request(shipper, recipient, package) # => #<SimpleShipping::Fedex::Response ...>
+  class Client < SimpleShipping::Abstract::Client
+    set_required_credentials :key, :password, :account_number, :meter_number
+
+    set_wsdl_document       File.join(SimpleShipping::WSDL_DIR, "fedex/ship_service_v10.wsdl")
+    set_testing_address     "https://wsbeta.fedex.com:443/web-services/ship"
+    set_production_address  "https://wsbeta.fedex.com:443/web-services/ship" # Not configured
+
+    # Send the shipment request to FedEx.
+    def shipment_request(shipper, recipient, package, opts = {})
+      shipment = create_shipment(shipper, recipient, package, opts)
+      request = ShipmentRequest.new(@credentials, shipment)
+      execute(request)
+    end
+
+    # Send the shipment confirmation request.
+    def ship_confirm_request(shipper, recipient, package, opts = {})
+      fail "Not Implemented"
+    end
+
+    # Send the ProcessShipmentRequest request to the FedEx service and return
+    # the response wrapped in a {Fedex::Response} object.
+    def execute(request)
+      savon_response = @client.call(request.type, :message => request.body)
+      request.response(savon_response)
+    end
+    private :execute
+  end
+end

data/lib/simple_shipping/fedex/package_builder.rb

@@ -0,0 +1,24 @@
+module SimpleShipping::Fedex
+  # Knows how to convert {Package} model to SOAP element for FedEx.
+  class PackageBuilder < SimpleShipping::Abstract::Builder
+    # FedEx mapping for weight units.
+    WEIGHT_UNITS = {:kg => 'KG',
+                    :lb => 'LB'}
+    # FedEx mapping for dimension units.
+    DIMENSION_UNITS = {:in => 'IN',
+                       :cm => 'CM'}
+    
+    # Build a SOAP package element as a hash for Savon.
+    def build
+      { 'Weight'     => {'Units' => WEIGHT_UNITS[@model.weight_units],
+                         'Value' => @model.weight,
+                         :order! => ['Units', 'Value']},
+        'Dimensions' => {'Length' => @model.length,
+                         'Width'  => @model.width,
+                         'Height' => @model.height,
+                         'Units'  => DIMENSION_UNITS[@model.dimension_units],
+                         :order!  => ['Length', 'Width', 'Height', 'Units']},
+        :order! => ['Weight',  'Dimensions']}
+    end
+  end
+end

data/lib/simple_shipping/fedex/party_builder.rb

@@ -0,0 +1,50 @@
+module SimpleShipping::Fedex
+  # Knows how to convert {Party} model to SOAP element for FedEx.
+  class PartyBuilder < SimpleShipping::Abstract::Builder
+    # Build a SOAP party element as a hash for Savon.
+    def build
+      {'Contact' => build_contact,
+       'Address' => build_address,
+       :order!   => ['Contact', 'Address']}
+    end
+
+    # Build the body for a Contact element.
+    #
+    # @return [Hash]
+    def build_contact
+      result  = {:order! => []}
+      contact = @model.contact
+      if contact.company_name
+        result['CompanyName'] = contact.company_name
+        result[:order!] << 'CompanyName'
+      end
+      if contact.person_name
+        result['PersonName']  = contact.person_name
+        result[:order!] << 'PersonName'
+      end
+      result['PhoneNumber'] = contact.phone_number
+      result[:order!] << 'PhoneNumber'
+      result
+    end
+    private :build_contact
+
+    # Build body for Address element.
+    #
+    # @return [Hash]
+    def build_address
+      addr = @model.address
+      {'StreetLines'         => addr.street_line,
+       'City'                => addr.city,
+       'StateOrProvinceCode' => addr.state_code,
+       'PostalCode'          => addr.postal_code,
+       'CountryCode'         => addr.country_code,
+       :order!               => [ 'StreetLines',
+                                  'City',
+                                  'StateOrProvinceCode',
+                                  'PostalCode',
+                                  'CountryCode' ]
+      }
+    end
+    private :build_address
+  end
+end

data/lib/simple_shipping/fedex/request.rb

@@ -0,0 +1,54 @@
+module SimpleShipping::Fedex
+  # Builds a complete request for the FedEx service.
+  class Request < SimpleShipping::Abstract::Request
+    extend ActiveSupport::Autoload
+
+    autoload :ShipmentRequest
+
+    def initialize(credentials, shipment)
+      super(credentials)
+      @shipment = shipment
+    end
+
+    # Build a complete request from a {Shipment shipment} object.
+    def body(opts = {})
+      {'WebAuthenticationDetail' => web_authentication_detail,
+       'ClientDetail'            => client_detail,
+       'Version'                 => version,
+       'RequestedShipment'       => ShipmentBuilder.build(@shipment, opts),
+       :order! => ['WebAuthenticationDetail', 'ClientDetail', 'Version', 'RequestedShipment'] }
+    end
+
+    # Build the body for the WebAuthenticationDetail element.
+    #
+    # @return [Hash]
+    def web_authentication_detail
+      { 'UserCredential' => {'Key'      => @credentials.key,
+                             'Password' => @credentials.password,
+                             :order!    => ['Key', 'Password']}}
+    end
+    private :web_authentication_detail
+
+    # Build the body for the UserCredential element.
+    #
+    # @return [Hash]
+    def client_detail
+      {'AccountNumber' => @credentials.account_number,
+       'MeterNumber'   => @credentials.meter_number,
+       :order!         => ['AccountNumber', 'MeterNumber']}
+    end
+    private :client_detail
+
+    # Build the body for the Version element.
+    #
+    # @return [Hash]
+    def version
+      {'ServiceId'    => 'ship',
+       'Major'        => '10',
+       'Intermediate' => '0',
+       'Minor'        => '0',
+       :order!        => ['ServiceId', 'Major', 'Intermediate', 'Minor']}
+    end
+    private :version
+  end
+end

data/lib/simple_shipping/fedex/response.rb

@@ -0,0 +1,5 @@
+module SimpleShipping::Fedex
+  # A wrapper for FedEx response.
+  class Response < SimpleShipping::Abstract::Response
+  end
+end

data/lib/simple_shipping/fedex/shipment_builder.rb

@@ -0,0 +1,123 @@
+module SimpleShipping::Fedex
+  # Builds a shipment element for FedEx SOAP service.
+  class ShipmentBuilder < SimpleShipping::Abstract::Builder
+    # Value for RateRequestTypes XML element.
+    RATE_REQUEST_TYPE = 'ACCOUNT'
+
+    # Number of packages.
+    PACKAGE_COUNT = '1'
+
+    # Mapping for package types
+    PACKAGING_TYPES = {
+      :box_10kg => 'FEDEX_10KG_BOX',
+      :box_25kg => 'FEDEX_25KG_BOX',
+      :box      => 'FEDEX_BOX',
+      :envelope => 'FEDEX_ENVELOPE',
+      :pak      => 'FEDEX_PAK',
+      :tube     => 'FEDEX_TUBE',
+      :your     => 'YOUR_PACKAGING'
+    }
+
+    # Mapping for service types
+    SERVICE_TYPES = {
+      :europe_first_international_priority => 'EUROPE_FIRST_INTERNATIONAL_PRIORITY',
+      :fedex_1_day_freight                 => 'FEDEX_1_DAY_FREIGHT',
+      :fedex_2_day_am                      => 'FEDEX_2_DAY',
+      :fedex_2_day_freight                 => 'FEDEX_2_DAY_AM',
+      :fedex_3_day_freight                 => 'FEDEX_2_DAY_FREIGHT',
+      :fedex_3_day_freight                 => 'FEDEX_3_DAY_FREIGHT',
+      :fedex_express_saver                 => 'FEDEX_EXPRESS_SAVER',
+      :fedex_freight_economy               => 'FEDEX_FIRST_FREIGHT',
+      :fedex_freight_economy               => 'FEDEX_FREIGHT_ECONOMY',
+      :fedex_freight_priority              => 'FEDEX_FREIGHT_PRIORITY',
+      :fedex_ground                        => 'FEDEX_GROUND',
+      :first_overnight                     => 'FIRST_OVERNIGHT',
+      :ground_home_delivery                => 'GROUND_HOME_DELIVERY',
+      :international_economy               => 'INTERNATIONAL_ECONOMY',
+      :international_economy_freight       => 'INTERNATIONAL_ECONOMY_FREIGHT',
+      :international_first                 => 'INTERNATIONAL_FIRST',
+      :international_priority              => 'INTERNATIONAL_PRIORITY',
+      :international_priority_freight      => 'INTERNATIONAL_PRIORITY_FREIGHT',
+      :priority_overnight                  => 'PRIORITY_OVERNIGHT',
+      :smart_post                          => 'SMART_POST',
+      :standard_overnight                  => 'STANDARD_OVERNIGHT'
+    }
+
+    # Mapping for dropoff types.
+    DROPOFF_TYPES = {
+      :business_service_center => 'BUSINESS_SERVICE_CENTER',
+      :drop_box                => 'DROP_BOX',
+      :regular_pickup          => 'REGULAR_PICKUP',
+      :request_courier         => 'REQUEST_COURIER',
+      :station                 => 'STATION'
+    }
+
+    set_default_opts :dropoff_type => :business_service_center,
+                     :service_type => :fedex_ground
+
+    # Build the shipment representation as a hash for the Savon client.
+    def build
+      {'ShipTimestamp'             => ship_timestamp,
+       'DropoffType'               => DROPOFF_TYPES[@opts[:dropoff_type]],
+       'ServiceType'               => SERVICE_TYPES[@opts[:service_type]],
+       'PackagingType'             => PACKAGING_TYPES[@model.package.packaging_type],
+       'Shipper'                   => PartyBuilder.build(@model.shipper),
+       'Recipient'                 => PartyBuilder.build(@model.recipient),
+       'ShippingChargesPayment'    => shipping_charges_payment,
+       'LabelSpecification'        => label_specification,
+       'RateRequestTypes'          => RATE_REQUEST_TYPE,
+       'PackageCount'              => PACKAGE_COUNT,
+       'RequestedPackageLineItems' => PackageBuilder.build(@model.package),
+       :order! => ['ShipTimestamp'   , 'DropoffType'    , 'ServiceType'           , 'PackagingType',
+                   'Shipper'         , 'Recipient'      , 'ShippingChargesPayment', 'LabelSpecification',
+                   'RateRequestTypes', 'PackageCount'   , 'RequestedPackageLineItems']
+      }
+    end
+
+    # Perform validations.
+    def validate
+      validate_inclusion_of(:dropoff_type  , DROPOFF_TYPES)
+      validate_inclusion_of(:service_type  , SERVICE_TYPES)
+    end
+
+    # Get the shipping timestamps in a specific format.
+    #
+    # @example
+    #   ship_timestamp  # => "2014-01-08T14:41:53+02:00"
+    #
+    # @return [String]
+    def ship_timestamp
+      Time.new.strftime('%Y-%m-%dT%H:%M:%S%z').tap{|str| str[-2,0] = ':' }
+    end
+    private :ship_timestamp
+
+    # Build the hash for the ShippingChargesPayment element.
+    #
+    # @return [Hash]
+    def shipping_charges_payment
+      {'PaymentType' => payment_type,
+       'Payor'       => {'AccountNumber' => @model.payor_account_number},
+       :order! => ['PaymentType', 'Payor']}
+    end
+    private :shipping_charges_payment
+
+    # Get the payment type.
+    #
+    # @return [String]
+    def payment_type
+      (@model.payor == :shipper) ? 'SENDER' : 'RECIPIENT'
+    end
+    private :payment_type
+
+    # Build the label parameters according to FedEx's API.
+    #
+    # @return [Hash]
+    def label_specification
+      { 'LabelFormatType' => 'COMMON2D',
+        'ImageType'       => 'PNG',
+        'LabelStockType'  => 'PAPER_4X6',
+        :order!           => ['LabelFormatType', 'ImageType', 'LabelStockType'] }
+    end
+    private :label_specification
+  end
+end