dhl-get_quote 0.4.25

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.rvmrc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.rvmrc.example

@@ -0,0 +1 @@
+rvm --create use ruby-1.9.3@dhl-get_quote

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 1.9.2
+  - rbx-18mode
+  - rbx-19mode
+  - 1.8.7
+  - ree
+  - jruby-19mode
+  - jruby-18mode

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in dhl-get_quote.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Deseret Book
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,357 @@
+[![Build Status](https://travis-ci.org/deseretbook/dhl-get_quote.png)](https://travis-ci.org/deseretbook/dhl-get_quote)
+
+# Dhl::GetQuote
+
+Get shipping quotes from DHL's XML-PI Service.
+
+Use of the XML-PI Service requires you to have Site ID and Password from DHL. You can sign up here: https://myaccount.dhl.com/MyAccount/jsp/TermsAndConditionsIndex.htm
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'dhl-get_quote'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install dhl-get_quote
+
+## Basic Usage
+
+```ruby
+  require 'dhl-get_quote'
+
+  r = Dhl::GetQuote::Request.new(
+    :site_id => "SiteIdHere",
+    :password => "p4ssw0rd",
+    :test_mode => true # changes the url being hit
+  )
+
+  r.kilograms!
+  r.centimeters!
+
+  r.add_special_service("DD")
+
+  r.to('CA', "T1H 0A1")
+  r.from('US', 84010)
+
+  r.pieces << Dhl::GetQuote::Piece.new(
+    :height => 20,
+    :weight => 20,
+    :width => 20,
+    :depth => 19
+  )
+
+  resp = r.post
+  if response.error?
+    raise "There was an error: #{resp.raw_xml}"
+  else
+    puts "Your cost to ship will be: #{resp.total_amount} in #{resp.currency_code}."
+  end
+```
+
+---
+
+### Dhl::GetQuote::Request
+
+#### Making a new request
+
+This is where the magic starts. It accepts a hash that, at minimum, requires :site\_id and :password. Optionally, :test\_mode may be passed in to tell the gem to use the XML-PI test URL. The default is to *not* use test mode and to hit the production URL.
+
+```ruby
+request = Dhl::GetQuote::Request.new(
+  :site_id => "SiteIdHere",
+  :password => "p4ssw0rd",
+  :test_mode => false
+)
+```
+
+*NOTE*: You can also set default beforehand in, for example, an initializer. For more information on this, please see the section "Initializers with Dhl::GetQuote"
+
+#### Package Source and Destination
+
+To set the source and destination, use the #to() and #from() methods:
+
+  #to(_country_code_, _postal_code_), #from(_country_code_, _postal_code_)
+
+The country code must be the two-letter capitalized ISO country code. The postal code will be cast in to a string.
+
+Example:
+
+```ruby
+  request.from('US', 84111)
+  request.to('CA', 'T1H 0A1')
+```
+
+#### Measurement Units
+
+DHL can accept weights and measures in both Metric and US Customary units.  Weights are given in either pounds or kilograms, dimensions in either inches or centimeters. This gem defaults to use metric measurements.
+
+To set to US Customary, use:
+
+```ruby
+  request.inches! # set dimensions to inches
+  request.pounds! # set weight to pounds
+```
+
+To set back to Metric, use
+
+```ruby
+  request.centimeters! # set dimensions to centimeters
+  request.centimetres! # alternate spelling
+
+  request.kilograms!   # set weight to kilograms
+  request.kilogrammes! # alternate spelling
+```
+
+To query what measurement system the object is currently using, use the following boolean calls:
+
+```ruby
+  request.inches?
+  request.centimeters? # or request.centimetres?
+
+  request.pounds?
+  request.kilograms? # or request.kilogrammes?
+```
+
+You can also get the value directly:
+
+```ruby
+  request.dimensions_unit # will return either "CM" or "IN"
+  request.weight_unit     # will return either "KG" or "LB"
+```
+
+#### Setting Duty
+
+You can toggle whether or not a shipment is dutiable with the #dutiable!() and #not_dutiable!() methods.
+
+```ruby
+  request.dutiable!
+  request.not_dutiable!
+```
+
+You can absolutely set the dutiable stage with the #dutiable() method:
+
+```ruby
+  request.dutiable(true)
+  request.dutiable(false)
+```
+
+You can query the current state with #dutiable?:
+
+```ruby
+  request.dutiable? # returns true or false
+```
+
+The default is for the request is "not dutiable".
+
+#### Shipment Services
+
+Shipment services (speed, features, etc) can be added, listed and removed.
+
+To add a special service, call #add_special_service as pass in DHL-standard code for the service:
+
+```ruby
+  request.add_special_service("D")
+```
+
+To list all services currently added to a request, use #special_services:
+
+```ruby
+  request.special_services
+```
+
+To remove a special service, use #remove_special_service and pass the code:
+
+```ruby
+  request.remove_special_service("D")
+```
+
+The interface will not allow the same special service code to be added twice, it will be silently ignored if you try.
+
+
+#### Adding items to the request
+
+To add items to the shipping quote request, generate a new Dhl::GetQuote::Piece instance and append it to #pieces:
+
+```ruby
+  # minimal
+  request.pieces << Dhl::GetQuote::Piece.new( :weight => 20 )
+
+  # more details
+  request.pieces << Dhl::GetQuote::Piece.new(
+    :weight => 20, :height => 20, :width => 20, :depth => 19
+  )
+```
+
+Dhl::GetQuote::Piece requires *at least* :weight to be specified, and it must be a nonzero integer.  Optionally, you can provide :width, :depth and :height. The measurement options must all be added at once and cannot be added individually. They must be integers.
+
+#### Posting to DHL
+
+Once the request is prepared, call #post() to post the request to the DHL XML-PI.  This will return a Dhl::GetQuote::Response object.
+
+```ruby
+  response = request.post
+  response.class == Dhl::GetQuote::Response # true
+```
+
+---
+
+### Dhl::GetQuote::Response
+
+Once a post is sent to DHL, this gem will interpret the XML returned and create a Dhl::GetQuote::Response object.
+
+#### Checking for errors
+
+To check for errors in the response (both local and upstream), query the #error? and #error methods
+
+```ruby
+  response.error? # true
+  response.error
+  # => < Dhl::GetQuote::Upstream::ValidationFailureError: your site id is not correct blah blah >
+```
+
+#### Getting costs
+
+The response object exposes the following values:
+
+  * currency_code
+  * currency_role_type_code
+  * weight_charge
+  * total_amount
+  * total_tax_amount
+  * weight_charge_tax
+
+To find the total change:
+
+```ruby
+  puts "Your cost to ship will be: #{response.total_amount} in #{response.currency_code}."
+  # Your cost to ship will be: 337.360 in USD.
+```
+
+DHL can return the cost in currency unit based on sender location or reciever location. It is unlikely this will be used much, but you can change the currency by calling #load_costs with the CurrencyRoleTypeCode:
+
+```ruby
+  response.load_costs('PULCL')
+  puts "Your cost to ship will be: #{response.total_amount} in #{response.currency_code}."
+  # Your cost to ship will be: 341.360 in CAD.
+```
+
+CurrencyRoleTypeCodes that can be used are:
+
+  * BILLCU – Billing currency
+  * PULCL – Country of pickup local currency
+  * INVCU – Invoice currency
+  * BASEC – Base currency
+
+#### Accessing the raw response
+
+If you need data from the response that is not exposed by this gem, you can access both the raw xml and parsed xml directly:
+
+```ruby
+  response.raw_xml    # raw xml string as returned by DHL
+  response.parsed_xml # xml parsed in to a Hash for easy traversal
+```
+
+\#parsed\_xml() is not always available in the case of errors. #raw\_xml() is, except in cases of network transport errors.
+
+#### Accessing offered services
+
+In cases where you have either sent many special service code, or you are evaluating all available services (via the 'OSINFO' special service code), you can obtain a list of all the services with the #offred_services() and #all_services() methods. Both methods return an array of Dhl::GetQuote::MarketService objects.
+
+The #offered_services() method returns only those services intended to be shown to the end user an optional services (XCH) they can apply. These would be services with either 'TransInd' or 'MrkSrvInd' set to 'Y'.
+
+The #all_services() methods returns all associated services, including everything in #offered_services and also including possible fees (FEE) and surcharges (SCH).
+
+If using 'OSINFO' to obtain all offered services, you pass the value of #code() in to Request#add_special_service() to apply this services to another request:
+
+```ruby
+  # assume we already did an 'OSINFO' request.
+  new_request.add_special_service(response.offered_services.first.code)
+```
+
+---
+
+### Dhl::GetQuote::MarketService
+
+Instances of this object are returned from Response#offered_services() and Response#all_services().
+
+#### Methods for parameters
+
+All XML parameters in the response will be added as methods to this object.  They may vary but generally include:
+
+* #local\_product\_code() - code for user-offered services (signature, tracking, overnight, etc)
+* #local\_service_type() code for non-offered special services (fees, surcharges, etc)
+* #local\_service\_type\_name() - Name for a non-offered service
+* #local\_product\_name() - Name for a user-offered service
+* #mrk\_srv\_ind() - Should this be offered to the user?
+* #trans\_ind() - Should this be shown to every user regardless of shipping options?
+
+#### Getting the code for a service
+
+The #code() method will return the code for a given service. It will work on both non-offered and user-offered services, it queries both LocalProductCode and LocalServiceType.
+
+```ruby
+  market_service.code # "D"
+```
+
+This code can be passed in to Request#add_special_service()
+
+#### Getting the name for a service
+
+The #name() method will return the name for a given service. It will work on both non-offered and user-offered services, it queries both LocalProductName and LocalServiceTypeName.
+
+```ruby
+  market_service.name # "EXPRESS WORLDWIDE DOC"
+```
+
+---
+
+### Initializers with Dhl::GetQuote
+
+If you don't want to have to pass email, password, weight setting, etc, every time you build a new request object you can set these defaults beforehand. This works well in cases where you want to put setting in something like a Rails initializer.
+
+To do this, call Dhl::GetQuote::configure and pass a block:
+
+```ruby
+  Dhl::GetQuote::configure do |c|
+
+    c.side_id  "SomeSiteId"
+    c.password "p4ssw0rd"
+
+    c.production_mode! # or test_mode!
+
+    c.kilograms!   # or kilogrammes!
+    c.centimeters! # or centimetres!
+    c.inches!
+    c.pounds!
+
+    c.dutiable! # or not_dutiable!
+
+  end
+```
+
+The above block sets defaults for use thereafter. You would then not have to pass site\_id or password in to Dhl::GetQuote::new():
+
+```ruby
+  Dhl::GetQuote::configure do
+    side_id  "SomeSiteId"
+    password "p4ssw0rd"
+  end
+
+  request = Dhl::GetQuote::new()
+```
+
+*Note*: options passed in to _Dhl::GetQuote::new()_ will override setting in the _Dhl::GetQuote::configure_ block.
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Add tests, make sure existing tests pass.
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+require "rspec/core/version"
+
+task :default => :spec
+
+desc "Run all examples"
+RSpec::Core::RakeTask.new(:spec, :default) do |t|
+  t.ruby_opts = %w[-w]
+end

data/dhl-get_quote.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'dhl/get_quote/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "dhl-get_quote"
+  gem.version       = Dhl::GetQuote::VERSION
+  gem.authors       = ["Deseret Book", "Matthew Nielsen"]
+  gem.email         = ["mnielsen@deseretbook.com"]
+  gem.description   = %q{Get shipping quotes from DHL}
+  gem.summary       = %q{Gem to interface with DHL's XML-PI shipping quote service.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency 'httparty', '~>0.10.2'
+  gem.add_dependency 'multi_xml', '~>0.5.3'
+
+  gem.add_development_dependency 'rake', '~>10.0.4'
+  gem.add_development_dependency 'rake', '10.0.4'
+  gem.add_development_dependency 'rspec', '2.13.0'
+  gem.add_development_dependency 'rspec-must', '0.0.1'
+  # gem.add_development_dependency 'autotest'
+  # gem.add_development_dependency 'debugger'
+
+end

data/lib/dhl/get_quote/errors.rb

@@ -0,0 +1,13 @@
+class Dhl::GetQuote
+  class InputError < StandardError; end
+  class OptionsError < InputError; end
+  class FromNotSetError < InputError; end
+  class ToNotSetError < InputError; end
+  class CountryCodeError < InputError; end
+  class PieceError < InputError; end
+
+  class Upstream < StandardError
+    class UnknownError < Upstream; end
+    class ValidationFailureError < Upstream; end
+  end
+end

data/lib/dhl/get_quote/helper.rb

@@ -0,0 +1,16 @@
+module Dhl::GetQuote::Helper
+  def underscore(camel_cased_word)
+    self.class.underscore(camel_cased_word)
+  end
+
+  module ClassMethods
+    def underscore(camel_cased_word)
+      camel_cased_word.gsub(/([A-Z]{1})([A-Z]{1})/,'\1_\2').gsub(/([a-z\d])([A-Z])/,'\1_\2').downcase
+    end
+  end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+end

data/lib/dhl/get_quote/market_service.rb

@@ -0,0 +1,42 @@
+class Dhl::GetQuote::MarketService
+  include Dhl::GetQuote::Helper
+
+  def initialize(options)
+    @options = {}
+    if options.class.to_s == 'Hash'
+      build_from_hash(options)
+    else
+      build_from_xml(options.to_s)
+    end
+  end
+
+  def code
+    @local_service_type || @local_product_code
+  end
+
+  def name
+    @local_service_type_name || @local_product_name
+  end
+
+protected
+
+  def build_from_xml(xml_string)
+    @parsed_xml = MultiXml.parse(xml_string)
+
+    @parsed_xml['MrkSrv'].each do |k,v|
+      @options[k] = v
+      instance_variable_set("@#{underscore(k)}".to_sym, v)
+      self.class.class_eval { attr_reader underscore(k).to_sym }
+    end
+  end
+
+  def build_from_hash(options)
+    options.each do |k,v|
+      k = underscore(k) if k =~ /[A-Z]/
+      @options[k] = v
+      instance_variable_set("@#{k}".to_sym, v)
+      self.class.class_eval { attr_reader k.to_sym }
+    end
+  end
+
+end

data/lib/dhl/get_quote/piece.rb

@@ -0,0 +1,59 @@
+class Dhl::GetQuote::Piece
+  attr_accessor :piece_id
+
+  def initialize(options = {})
+    [ :width, :height, :depth, :weight ].each do |i|
+      options[i] = options[i].to_i if !!options[i]
+    end
+
+    if options[:weight] && options[:weight] > 0
+      @weight = options[:weight]
+    else
+      raise Dhl::GetQuote::OptionsError, required_option_error_message(:weight)
+    end
+
+    if options[:width] || options[:height] || options[:depth]
+      [ :width, :height, :depth ].each do |req|
+        if options[req].to_i > 0
+          instance_variable_set("@#{req}", options[req].to_i)
+        else
+          raise Dhl::GetQuote::OptionsError, required_option_error_message(req)
+        end
+      end
+    end
+
+    @piece_id = options[:piece_id] || 1
+
+  end
+
+  def to_h
+    h = {}
+    [ :width, :height, :depth, :weight ].each do |req|
+      if x = instance_variable_get("@#{req}")
+        h[req.to_s.capitalize] = x
+      end
+    end
+    h
+  end
+
+  def to_xml
+    xml_str = <<eos
+<Piece>
+  <PieceID>#{@piece_id}</PieceID>
+eos
+
+    xml_str << "  <Height>#{@height}</Height>\n" if @height
+    xml_str << "  <Depth>#{@depth}</Depth>\n" if @depth
+    xml_str << "  <Width>#{@width}</Width>\n" if @width
+    xml_str << "  <Weight>#{@weight}</Weight>\n" if @weight
+
+    xml_str += "</Piece>\n"
+    xml_str
+  end
+
+private
+
+  def required_option_error_message(field)
+    ":#{field} is a required for Dhl::GetQuote::Piece. Must be nonzero integer."
+  end
+end