simple_shipping 0.4.6

data/lib/simple_shipping/fedex/shipment_request.rb

@@ -0,0 +1,14 @@
+module SimpleShipping::Fedex
+  # The model that represents shipment request to FedEx.
+  class ShipmentRequest < Request
+    def initialize(credentials, shipment)
+      super
+      @type = :process_shipment
+    end
+
+    # :nodoc:
+    def response_class
+      ShipmentResponse
+    end
+  end
+end

data/lib/simple_shipping/fedex/shipment_response.rb

@@ -0,0 +1,12 @@
+module SimpleShipping::Fedex
+  # A wrapper for UPS ShipmentResponse.
+  class ShipmentResponse < Response
+    # Get the label as abstract64 encoded data
+    #   response.label_image_base64 # => "odGqk/KmgLaawV..."
+    # This can be used directly in an HTML image tag with
+    #   src="data:image/gif;base64,..."
+    def label_image_base64
+      value_of(:process_shipment_reply, :completed_shipment_detail, :completed_package_details, :label, :parts, :image)
+    end
+  end
+end

data/lib/simple_shipping/package.rb

@@ -0,0 +1,43 @@
+module SimpleShipping
+  # Represents a package which should be sent from {SimpleShipping::Party shipper}
+  # to {SimpleShipping::Party recipient}.
+  #
+  # == Attributes:
+  # * _dimenstion_units_ (:in, :cm). Default is :in.
+  # * _weight_units_ (:kg, :lb). Default is :lb.
+  # * _legth_ (in dimension units)
+  # * _width_ (in dimension units)
+  # * _height_ (in dimension units)
+  # * _weight_ (in weight  units)
+  # * _packaging_type_ 
+  #
+  # == Packaging type values:
+  # * :envelope
+  # * :your
+  # * :tube
+  # * :pak
+  # * :box
+  # * :box_10kg
+  # * :box_25kg
+  class Package < Abstract::Model
+    attr_accessor :length, :width, :height, :dimension_units
+    attr_accessor :weight, :weight_units, :packaging_type
+    attr_accessor :insured_value, :declared_value
+
+    validates_presence_of :length, :width, :height, :dimension_units, :if => :custom_package?
+    validates_presence_of :weight, :weight_units
+
+    validates_inclusion_of :weight_units   , :in => [:kg, :lb]
+    validates_inclusion_of :dimension_units, :in => [:in, :cm], :if => :custom_package?
+    validates_inclusion_of :packaging_type , :in => [:envelope, :pak, :tube, :your, :box, :box_10kg, :box_25kg]
+
+    set_default_values :packaging_type  => :your,
+                       :weight_units    => :lb,
+                       :dimension_units => :in
+
+    # Whether the package is a custom package.
+    def custom_package?
+      packaging_type == :your
+    end
+  end
+end

data/lib/simple_shipping/party.rb

@@ -0,0 +1,21 @@
+module SimpleShipping
+  # Party is a person or company who takes a part in shipment process.
+  # Party is used to represent a shipper or a recipient.
+  #
+  # == Attributes
+  # * _contact_ (instance of {SimpleShipping::Contact})
+  # * _address_ (instance of {SimpleShipping::Address})
+  # * _account_number_ (optional, but in some cases required)
+  #
+  # If one of attributes is missed an appropriate exception will be raised
+  # when you build a request.
+  class Party < Abstract::Model
+    attr_accessor :contact,
+                  :address,
+                  :account_number
+
+    validates_presence_of :contact, :address
+    validates_submodel :address, :as => SimpleShipping::Address
+    validates_submodel :contact, :as => SimpleShipping::Contact
+  end
+end

data/lib/simple_shipping/shipment.rb

@@ -0,0 +1,42 @@
+module SimpleShipping
+  # Represents a shipment.
+  #
+  # == Attributes:
+  # * _shipper_ (an instance of {SimpleShipping::Party}
+  # * _recipient_ (an instance of {SimpleShipping::Party}
+  # * _package_ (an instance of {SimpleShipping::Package}
+  # * _payor_  (:shipper, :recipient). Default value is :shipper
+  class Shipment < Abstract::Model
+    attr_accessor :shipper,
+                  :recipient,
+                  :package,
+                  :payor
+
+    set_default_values :payor => :shipper
+
+    validates_presence_of :shipper, :recipient, :package, :payor
+    validates_inclusion_of :payor, :in => [:shipper, :recipient]
+    validates_submodel :shipper  , :as => SimpleShipping::Party
+    validates_submodel :recipient, :as => SimpleShipping::Party
+    validates_submodel :package  , :as => SimpleShipping::Package
+    validate :validate_payor_account_number
+
+    # Account number of payor.
+    def payor_account_number
+      case payor
+      when :shipper
+        shipper.account_number   if shipper.respond_to?(:account_number)
+      when :recipient
+        recipient.account_number if recipient.respond_to?(:account_number)
+      end
+    end
+
+    # Validate presence of payor account number.
+    #
+    # @return [void]
+    def validate_payor_account_number
+      errors.add(:abstract, "Payor account number is missing") unless payor_account_number
+    end
+    private :validate_payor_account_number
+  end
+end

data/lib/simple_shipping/ups.rb

@@ -0,0 +1,24 @@
+# Namespace for UPS provider.
+module SimpleShipping::Ups
+  extend ActiveSupport::Autoload
+
+  autoload :Client
+  autoload :ShipClient
+  autoload :VoidClient
+
+  autoload :Request
+  autoload :Response
+  autoload :PackageBuilder
+  autoload :PartyBuilder
+  autoload :ShipmentBuilder
+
+  autoload :ShipConfirmResponse
+  autoload :ShipAcceptResponse
+  autoload :ShipmentResponse
+  autoload :VoidResponse
+
+  autoload :ShipConfirmRequest
+  autoload :ShipAcceptRequest
+  autoload :ShipmentRequest
+  autoload :VoidRequest
+end

data/lib/simple_shipping/ups/client.rb

@@ -0,0 +1,46 @@
+module SimpleShipping::Ups
+  # Abstract class for all UPS clients.
+  # The problem with UPS is that its WSDL imports schemas. However schema imports are not supported
+  # by Savon as by v.2.1.0. See: https://github.com/savonrb/wasabi/issues/1
+  # Because of this we have to manually:
+  #   1. Assign additional namespaces
+  #   2. Switch to :qualified :elemen_form_default
+  #     (to have all requests elements prepended with namespace
+  #      if its namespace is not specified explicitly)
+  #   3. Explicitly prepend namespace to all elements which not belong to WSDL target namespace
+  #      i.e. UPSSecurity, Request/RequestOptions etc
+  #
+  class Client < SimpleShipping::Abstract::Client
+
+    # @param [Hash] options Savon client options
+    def client_options(options = {})
+      super.deep_merge(
+        :element_form_default => :qualified,
+        :namespaces => {
+          'xmlns:upss'   => "http://www.ups.com/XMLSchema/XOLTWS/UPSS/v1.0",
+          'xmlns:common' => "http://www.ups.com/XMLSchema/XOLTWS/Common/v1.0",
+        },
+        :soap_header => soap_header
+      )
+    end
+    protected :client_options
+
+    # @return [Hash] of SOAP envelope header contents
+    def soap_header
+      {
+        'upss:UPSSecurity' => {
+          'upss:UsernameToken' => {
+            'upss:Username' => @credentials.username,
+            'upss:Password' => @credentials.password,
+            :order!         => ['upss:Username', 'upss:Password']
+          },
+          'upss:ServiceAccessToken' => {
+            'upss:AccessLicenseNumber' => @credentials.access_license_number
+          },
+          :order! => ['upss:UsernameToken', 'upss:ServiceAccessToken']
+        }
+      }
+    end
+    protected :soap_header
+  end
+end

data/lib/simple_shipping/ups/package_builder.rb

@@ -0,0 +1,101 @@
+# Builds hash for Savon which represents {Package package}.
+module SimpleShipping::Ups
+  # Builds hash structure for Savon that represents package element in UPS's API.
+  class PackageBuilder < SimpleShipping::Abstract::Builder
+    # Mapping for UPS packaging types
+    # Not all UPS values listed here in order to provide common interface with FedEx.
+    PACKAGING_TYPES = {
+      :envelope => '01',  # letter
+      :your     => '02',  # customer supplied
+      :tube     => '03',  # tube
+      :pak      => '04',  # UPS Packaging
+      :box      => '2b',  # medium box
+      :box_10kg => '25',
+      :box_10kg => '24'
+    }
+
+    # Mapping for UPS weight units.
+    WEIGHT_UNITS = {
+      :kg => 'KGS',
+      :lb => 'LBS'
+    }
+
+    # Mapping for UPS dimension units.
+    DIMENSION_UNITS = {
+      :in => 'IN',
+      :cm => 'CM'
+    }
+
+    # Custom package order.
+    CUSTOM_PACKAGE_ORDER = %w(Packaging PackageServiceOptions Dimensions PackageWeight)
+
+    # Standard package order.
+    STANDARD_PACKAGE_ORDER = %w(Packaging PackageServiceOptions PackageWeight)
+
+    # Build basic skeleton for package element. It can be customized by
+    # overriding some subelements.
+    #
+    # @return [Hash]
+    def base_package
+      base = {
+        'Packaging' => {
+          'Code' => PACKAGING_TYPES[@model.packaging_type]
+        },
+        'PackageWeight' => {
+          'UnitOfMeasurement' => {
+            'Code' => WEIGHT_UNITS[@model.weight_units]
+          },
+          'Weight' => @model.weight,
+          :order!  => ['UnitOfMeasurement', 'Weight']
+        },
+        'PackageServiceOptions' => {}
+      }
+
+      if @model.insured_value
+        base['PackageServiceOptions']['InsuredValue'] = {
+          'CurrencyCode'  => 'USD',
+          'MonetaryValue' => @model.insured_value
+        }
+      end
+
+      if @model.declared_value
+        base['PackageServiceOptions']['DeclaredValue'] = {
+          'CurrencyCode'  => 'USD',
+          'MonetaryValue' => @model.declared_value
+        }
+      end
+
+      base
+    end
+
+    # Build a hash from a custom {Package package} which will be used by Savon.
+    # A custom package requires specification of LWH dimensions.
+    def custom_package
+      base_package.tap do |package|
+        package['Dimensions'] = {
+          'UnitOfMeasurement' => {
+            'Code' => DIMENSION_UNITS[@model.dimension_units].clone
+          },
+          'Length' => @model.length,
+          'Width'  => @model.width,
+          'Height' => @model.height,
+          :order! => ['UnitOfMeasurement', 'Length', 'Width', 'Height']
+        }
+        package[:order!] = CUSTOM_PACKAGE_ORDER.clone
+      end
+    end
+
+    # Build a hash from a standard {Package package} which will be used by Savon.
+    # A standard package requires no specification of LWH dimensions.
+    def standard_package
+      base_package.tap do |package|
+        package[:order!] = STANDARD_PACKAGE_ORDER.clone
+      end
+    end
+
+    # Build the package, whether custom or standard.
+    def build
+      @model.custom_package? ? custom_package : standard_package
+    end
+  end
+end

data/lib/simple_shipping/ups/party_builder.rb

@@ -0,0 +1,38 @@
+module SimpleShipping::Ups
+  # Knows how to convert {Party} model to SOAP element for UPS.
+  class PartyBuilder < SimpleShipping::Abstract::Builder
+    # Builds a hash for Savon which represents {Party party}.
+    def build
+      contact = @model.contact
+      {'Name'          => (contact.person_name || contact.company_name),
+       'Phone'         => {'Number' => contact.phone_number},
+       'ShipperNumber' => @model.account_number,
+       'Address'       => build_address,
+       :order!         => ['Name', 'Phone', 'ShipperNumber', 'Address']
+      }
+    end
+
+    # Build address element.
+    #
+    # @return [Hash]
+    def build_address
+      addr = @model.address
+      {'AddressLine'       => [addr.street_line, addr.street_line_2, addr.street_line_3].compact,
+       'City'              => addr.city,
+       'StateProvinceCode' => addr.state_code,
+       'PostalCode'        => addr.postal_code,
+       'CountryCode'       => addr.country_code,
+       :order!             => ['AddressLine', 'City', 'StateProvinceCode', 'PostalCode', 'CountryCode']
+      }
+    end
+
+    # Validate presence of account_number.
+    #
+    # @return [void]
+    def validate
+      if @opts[:shipper] && !@model.account_number
+        raise SimpleShipping::ValidationError.new("account_number is required for party who is shipper")
+      end
+    end
+  end
+end

data/lib/simple_shipping/ups/request.rb

@@ -0,0 +1,27 @@
+module SimpleShipping::Ups
+  # Builds complete request for UPS
+  class Request < SimpleShipping::Abstract::Request
+    # Value for <common:RequestOption> XML element in request.
+    REQUEST_OPTION = 'nonvalidate'
+
+    # Define label parameters according to UPS's API.
+    #
+    # @return [Hash]
+    def label_specification
+      { 'LabelImageFormat' => {'Code' => 'GIF'},
+        'LabelStockSize'   => {
+          'Height' => '6',
+          'Width'  => '4',
+          :order!  => ['Height', 'Width']
+        },
+        :order! => ['LabelImageFormat', 'LabelStockSize']
+      }
+    end
+
+    # The class of the response in the same name space.
+    def response_class
+      self.class.name.sub(/Request/, 'Response').constantize
+    end
+    private :response_class
+  end
+end

data/lib/simple_shipping/ups/response.rb

@@ -0,0 +1,63 @@
+module SimpleShipping::Ups
+  # Response from UPS.
+  class Response < SimpleShipping::Abstract::Response
+    # Digest what can be used to get a label.
+    #
+    # @return [String]
+    def digest
+      value_of(:shipment_results, :shipment_digest)
+    end
+
+    # Unique shipment ID returned by UPS.
+    #
+    # @return [Strig]
+    def shipment_identification_number
+      value_of(:shipment_results, :shipment_identification_number)
+    end
+
+    # Get package tracking number to look for delivery process on UPS site.
+    #
+    # @return [String] tracking number
+    def tracking_number
+      value_of(:shipment_results, :package_results, :tracking_number)
+    end
+
+    # Get the label as base64 encoded data
+    #   response.label_image_base64 # => "odGqk/KmgLaawV..."
+    # This can be used directly in an HTML image tag with
+    #   src="data:image/gif;base64,..."
+    def label_image_base64
+      value_of(:shipment_results, :package_results, :shipping_label, :graphic_image)
+    end
+
+    # Label image.
+    #
+    # @return [String] binary
+    def label_html
+      value = value_of(:shipment_results, :package_results, :shipping_label, :html_image)
+      Base64.decode64(value) if value
+    end
+
+    # Receipt.
+    #
+    # @return [String] binary
+    def receipt_html
+      value = value_of(:shipment_results, :control_log_receipt, :graphic_image)
+      Base64.decode64(value) if value
+    end
+
+    # Fetch the value of an XML attribute at the path specified as an array
+    # of node names but appends the implicit namespace on to the front of the
+    # path.
+    def value_of(*path)
+      super(*path.unshift(name_token))
+    end
+
+    # All UPS requests are namespaced within the same name of the class by
+    # convention.
+    def name_token
+      self.class.name.split('::').last.underscore.to_sym
+    end
+    private :name_token
+  end
+end