simple_shipping 0.4.6

data/lib/colorized_text.rb

@@ -0,0 +1,34 @@
+# Colorizes text with ASCII colors.
+#
+# @example
+#   include ColorizedText
+#
+#   puts green "OK"          # => green output
+#   puts bold "Running...    # => bold output
+#   puts bold green "OK!!!"  # => bold green output
+module ColorizedText
+  # Colorize text using ASCII color code
+  def colorize(text, code)
+    "\033[#{code}m#{text}\033[0m"
+  end
+
+  # :nodoc:
+  def yellow(text)
+    colorize(text, 33)
+  end
+
+  # :nodoc:
+  def green(text)
+    colorize(text, 32)
+  end
+
+  # :nodoc:
+  def red(text)
+    colorize(text, 31)
+  end
+
+  # :nodoc:
+  def bold(text)
+    colorize(text, 1)
+  end
+end

data/lib/simple_shipping.rb

@@ -0,0 +1,27 @@
+require 'active_support/core_ext'
+require 'active_model'
+require 'savon'
+require 'ostruct'
+
+
+# Namespace for SimpleShipping library.
+module SimpleShipping
+  extend ActiveSupport::Autoload
+
+  # Path to the directory with WDSL files.
+  WSDL_DIR = File.expand_path("../../wsdl", __FILE__)
+
+  autoload :Abstract
+  autoload :Address
+  autoload :Contact
+  autoload :Demo
+  autoload :Package
+  autoload :Party
+  autoload :Shipment
+
+  autoload :Ups
+  autoload :Fedex
+end
+
+
+require 'simple_shipping/exceptions'

data/lib/simple_shipping/abstract.rb

@@ -0,0 +1,11 @@
+# Namespace for the abstract classes that define common interface for all
+# shipping providers.
+module SimpleShipping::Abstract
+  extend ActiveSupport::Autoload
+
+  autoload :Response
+  autoload :Model
+  autoload :Builder
+  autoload :Client
+  autoload :Request
+end

data/lib/simple_shipping/abstract/builder.rb

@@ -0,0 +1,47 @@
+module SimpleShipping
+  # Kind of an abstract class which should be used to create model builders.
+  # Model builder "knows" how to represent its model for a its service.
+  # This class provides only common skeleton for subclasses.
+  class Abstract::Builder
+    class_attribute :default_opts
+
+    # == Parameters:
+    #   model - kind of {Abstract::Model}
+    #   opts - hash of options. Every builder can have its own specific set of options
+    # == Returns:
+    #   Hash which can be used by Savon to build a part of SOAP request.
+    def self.build(model, opts = {})
+      raise(ValidationError.new(model)) unless model.valid?
+
+      builder = self.new(model, opts)
+      builder.validate
+      builder.build
+    end
+
+    # Allows to set default option values is subclasses.
+    def self.set_default_opts(opts = {})
+      self.default_opts = opts
+    end
+
+    # Should be implemented by subclasses. But by default returns empty hash.
+    def build; {}; end
+
+    # Should be implemented by subclass if subclass needs to do some validation.
+    def validate; end
+
+    def initialize(model = nil, opts = {})
+      self.default_opts ||= {}
+      @opts  = default_opts.merge(opts)
+      @model = model
+    end
+    private :initialize
+
+    # Raises {ValidationError} if option has invalid value.
+    def validate_inclusion_of(option, enumeration)
+      unless enumeration.has_key?(@opts[option])
+        raise ValidationError.new("#{option} has an unavailable value(#{@opts[option]}). Available values are #{enumeration.keys.inspect}") 
+      end
+    end
+    private :validate_inclusion_of
+  end
+end

data/lib/simple_shipping/abstract/client.rb

@@ -0,0 +1,111 @@
+module SimpleShipping
+  # Abstract class which provides common interfaces for the next concrete clients:
+  # * {Fedex::Client}
+  # * {Ups::Client}
+  class Abstract::Client
+    class_attribute :required_credentials,
+                    :wsdl_document,
+                    :production_address,
+                    :testing_address
+
+    # Set credentials which should be validated.
+    def self.set_required_credentials(*args)
+      self.required_credentials = args
+    end
+
+    # Set the WSDL document used by Savon.
+    def self.set_wsdl_document(wsdl_path)
+      self.wsdl_document = wsdl_path
+    end
+
+    # Set the production endpoint.
+    #
+    # @param address [String]
+    def self.set_production_address(address)
+      self.production_address = address
+    end
+
+    # Set the testing endpoint.
+    #
+    # @param address [String]
+    def self.set_testing_address(address)
+      self.testing_address = address
+    end
+
+    # Create an instance of a client.
+    # == Parameters:
+    #   * credentials - a hash with credentials.
+    def initialize(options)
+      @options    = options.dup
+      @live       = options.delete(:live)
+      @debug      = options.delete(:debug)
+      @debug_path = options.delete(:debug_path)
+      credentials = options.delete(:credentials)
+
+      validate_credentials(credentials)
+      @credentials = OpenStruct.new(credentials)
+
+      @client = Savon.client(client_options(options))
+    end
+
+    # @param [Hash] options Savon client options
+    # @return [Hash{Symbol => Object}] Savon client options
+    def client_options(options = {})
+      endpoint = @live ? self.class.production_address : self.class.testing_address
+
+      options.symbolize_keys.reverse_merge(
+        :wsdl     => wsdl_document,
+        :endpoint => endpoint
+      )
+    end
+    protected :client_options
+
+
+    # Validate that all required credentials are passed.
+    def validate_credentials(credentials)
+      credentials.assert_valid_keys(required_credentials)
+      missing = required_credentials - credentials.keys
+      raise(Error.new "The next credentials are missing for #{self}: #{missing.join(', ')}") unless missing.empty?
+    end
+    private :validate_credentials
+
+    # Build the {Shipment shipment} model.
+    def create_shipment(shipper, recipient, package, opts = {})
+      shipment = SimpleShipping::Shipment.new(
+        :shipper   => shipper,
+        :recipient => recipient,
+        :package   => package)
+      shipment.payor = opts[:payor] if opts[:payor]
+      shipment
+    end
+    private :create_shipment
+
+    # Write the request information to request.xml.
+    #
+    # @param soap [Savon::HTTPRequest]
+    def log_request(soap)
+      log_soap("request", soap)
+    end
+    private :log_request
+
+    # Write the response information to response.xml.
+    #
+    # @param [Savon::Response] soap
+    def log_response(soap)
+      log_soap("response", soap)
+    end
+    private :log_response
+
+    # Write the request/response to .xml file.
+    #
+    # @param name [String] file name without .xml
+    # @param soap [Savon::HTTPRequest, Savon::Response]
+    def log_soap(name, soap)
+      if @debug
+        path = File.join(@debug_path, "#{name}.xml")
+        File.open(path, 'w') {|f| f.write soap.to_xml}
+      end
+    end
+    private :log_soap
+  end
+end

data/lib/simple_shipping/abstract/model.rb

@@ -0,0 +1,40 @@
+module SimpleShipping
+# Base class for all simple shipping models.
+  class Abstract::Model
+    include ActiveModel::Validations
+
+    # hash with default attribute values
+    class_attribute :default_values
+
+    # Define the default values of the attributes which should be set when the model is created.
+    def self.set_default_values(values = {})
+      self.default_values = values 
+    end
+
+    # Add a validation callback to validate the submodel. Submodel is a model
+    # which belongs to current model.
+    # == Parameters:
+    # * name - name of attribute which is submodel
+    # * opts - hash with only on key :as. It should points to class of submodel.
+    def self.validates_submodel(name, opts = {})
+      validate do
+        klass = opts[:as] || raise(":as option should be passed")
+        submodel = send(name)
+        if !submodel.instance_of?(klass)
+          errors.add(name.to_sym, "must be an instance of #{klass.inspect}") 
+        elsif submodel.invalid?
+          errors.add(name.to_sym, "is invalid")
+        end
+      end
+    end
+
+    # Create a new model and set the default and passed values.
+    def initialize(values = {})
+      values.reverse_merge!(default_values || {})
+      values.each do |attribute, value|
+        raise("Undefined attribute `#{attribute}` for #{self}") unless respond_to?(attribute)
+        send("#{attribute}=", value)
+      end
+    end
+  end
+end

data/lib/simple_shipping/abstract/request.rb

@@ -0,0 +1,27 @@
+module SimpleShipping
+  # Base class for request builders. Every service has its own implementation.
+  class Abstract::Request
+    attr_reader :credentials
+    attr_reader :type
+
+    def initialize(credentials)
+      @credentials = credentials
+    end
+
+    # Wrap the Savon response with specific response for shipment provider.
+    #
+    # @param savon_response [Savon::Response]
+    #
+    # @return [SimpleShipping::Abstract::Response]
+    def response(savon_response)
+      response_class.new(savon_response)
+    end
+
+    # Response class to wrap Savon response.
+    #
+    # @return [Class]
+    def response_class
+      Response
+    end
+  end
+end

data/lib/simple_shipping/abstract/response.rb

@@ -0,0 +1,26 @@
+module SimpleShipping
+  # Represents a response returned by the remote service for a request initiated
+  # by {SimpleShipping::Abstract::Client client}.
+  #
+  # An abstract class which provides a common interface.
+  # In the real world, you will deal with its subclasses:
+  # * {SimpleShipping::Fedex::Response}
+  # * {SimpleShipping::Ups::Response}
+  #
+  # == Example:
+  #   response = client.request(shipper, recipient, package)
+  #   response.response # => #<Savon::SOAP::Response ...>
+  class Abstract::Response
+    attr_reader :response
+
+    def initialize(savon_resp = nil)
+      @response = savon_resp
+    end
+
+    # Fetch the value of an XML attribute at the path specified as an array.
+    # of node names
+    def value_of(*path)
+      @response.to_array(*path).first
+    end
+  end
+end

data/lib/simple_shipping/address.rb

@@ -0,0 +1,22 @@
+module SimpleShipping
+  # Represents an address information of {SimpleShipping::Party party}.
+  # == Attributes:
+  # * _country_code_
+  # * _state_code_
+  # * _city_
+  # * _street_line_
+  # * _street_line_2_
+  # * _street_line_3_
+  # * _postal_code_
+  class Address < Abstract::Model
+    attr_accessor :country_code,
+                  :state_code,
+                  :city,
+                  :street_line,
+                  :street_line_2,
+                  :street_line_3,
+                  :postal_code
+
+    validates_presence_of :country_code, :state_code, :city, :street_line, :postal_code
+  end
+end

data/lib/simple_shipping/contact.rb

@@ -0,0 +1,24 @@
+module SimpleShipping
+  # Represents the contact information of the {SimpleShipping::Party party} who takes
+  # part in shipment process.
+  #
+  # == Attributes
+  # * _person_name_ (optional if company_name is provided)
+  # * _company_name_ (optional if person_name is provided)
+  # * _phone_number_
+  # * _email_ (optional)
+  class Contact < Abstract::Model
+    attr_accessor :person_name,
+                  :company_name,
+                  :phone_number,
+                  :email
+
+    validates_presence_of :phone_number
+    validate :validate_name
+
+    # Validate presence of person or company name.
+    def validate_name
+      errors.add(:abstract, "person_name or company_name must be present") unless (person_name || company_name)
+    end
+  end
+end

data/lib/simple_shipping/demo.rb

@@ -0,0 +1,9 @@
+# Namespace for demo rake tasks used to test real remote requests by sending
+# test requests to verify credentials. Not intended for runtime use.
+class SimpleShipping::Demo
+  extend ActiveSupport::Autoload
+
+  autoload :Fedex
+  autoload :Ups
+  autoload :Base
+end

data/lib/simple_shipping/demo/base.rb

@@ -0,0 +1,71 @@
+# Base class for UPS and FedEx demos.
+class SimpleShipping::Demo::Base
+  attr_reader :options
+
+  # Build the shipper address with random attributes.
+  #
+  # @return [SimpleShipping::Address]
+  def shipper_address
+    @shipper_address ||= SimpleShipping::Address.new(
+        :country_code => 'US',
+        :state_code   => 'TX',
+        :city         => 'Texas',
+        :street_line  => 'SN2000 Test Meter 8',
+        :postal_code  => '73301'
+    )
+  end
+
+  # Build the shipper contact object.
+  #
+  # @return [SimpleShipping::Contact]
+  def shipper_contact
+    @shipper_contact ||= SimpleShipping::Contact.new(
+        :person_name  => 'Mister Someone',
+        :phone_number => '1234567890'
+    )
+  end
+
+  # Build the shipper object.
+  #
+  # @return [SimpleShipping::Party]
+  def shipper
+    @shipper ||= SimpleShipping::Party.new(
+        :address => shipper_address,
+        :contact => shipper_contact,
+        :account_number => options[:account_number]
+    )
+  end
+
+  # Build the recipient address with random attributes.
+  #
+  # @return [SimpleShipping::Address]
+  def recipient_address
+    @recipient_address ||= SimpleShipping::Address.new(
+        :country_code => 'US',
+        :state_code   => 'MN',
+        :city         => 'Minneapolis',
+        :street_line  => 'Nightmare Avenue 13',
+        :postal_code  => '55411'
+    )
+  end
+
+  # Build the recipient contact.
+  #
+  # @return [SimpleShipping::Contact]
+  def recipient_contact
+    @recipient_contact ||= SimpleShipping::Contact.new(
+      :person_name  => "John Recipient Smith",
+      :phone_number => "1234567890"
+  )
+  end
+
+  # Build the recipient object.
+  #
+  # @return [SimpleShipping::Party]
+  def recipient
+    @recipient ||= SimpleShipping::Party.new(
+      :address        => recipient_address,
+      :contact        => recipient_contact
+  )
+  end
+end