active_shipping 1.0.0.pre1 → 1.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8664d2221411bccc635ba71eae6bb4262d369753
-  data.tar.gz: b468c066831f372867d0cd3ecd70ed04069a4d08
+  metadata.gz: 73732fbdf2ce8048403b8039027c688126ba5233
+  data.tar.gz: 6f16c0d09ecd5392008b5cd6f20a401a0631d8b3
 SHA512:
-  metadata.gz: 4e7eb03007d6327ab42ee8aa9af0adfe741542769231354058a2cfbffa40399ef2ab7ab9eaf39c1f57b3e9ae2f12568c8156dd4c49be9769f149e974960f8149
-  data.tar.gz: 6d3b6f02166d9eed86426e74d1fca59f6737d21dc4410e36c0d1f65eb815d93fbf4587610c6889af02646e3f83f9b37b8df23f4fcddb56b6def3d09659f98b62
+  metadata.gz: 2f007d4d627a81ba03b03fc638520e1576087fec52ac0989046720505c8eb550a07ff3501b7e43966624f53d8e0ee6e161d06752c8edeafd8106b91935ff2d42
+  data.tar.gz: e56fe6610709fbdd802a3e3bcd573ac3465d97ed3e79a879ea4708520fb43a9658725af24f13a20bd6de0920727db4bbcc5f769ca6a2c61655b106d9c6997874

data/CONTRIBUTING.md

@@ -1,32 +1,45 @@
 # Contributing to ActiveShipping
 
-We welcome fixes and additions to this project. Please use clean, concise code that follows Ruby community standards. For example:
-
-* Be consistent
-* Don't use too much white space
-** Use 2 space indent, no tabs.
-** No spaces after (, [ and before ],)
-* Nor too little
-** Use spaces around operators and after commas, colons and semicolons
-** Indent when as deep as case
-* Write lucid code in lieu of adding comments
-
-## Contributors
-
-* James MacAulay (<http://jmacaulay.net>)
-* Tobias Luetke (<http://blog.leetsoft.com>)
-* Cody Fauser (<http://codyfauser.com>)
-* Jimmy Baker (<http://jimmyville.com/>)
-* William Lang (<http://williamlang.net/>)
-* Cameron Fowler
-* Christopher Saunders (<http://christophersaunders.ca>)
-* Denis Odorcic
-* Dennis O'Connor
-* Dennis Theisen
-* Edward Ocampo-Gooding
-* Isaac Kearse
-* John Duff
-* Nigel Ramsay
-* Philip Arndt
-* Vikram Oberoi
-* Willem van Bergen
+We welcome fixes and additions to this project. Fork this project, make your changes and submit a pull request!
+
+### Code style
+
+Please use clean, concise code that follows Ruby community standards. For example:
+
+- Be consistent
+- Don't use too much white space
+  - Use 2 space indent, no tabs.
+  - No spaces after (, [ and before ],)
+- Nor too little
+  - Use spaces around operators and after commas, colons and semicolons
+  - Indent when as deep as case
+- Write lucid code in lieu of adding comments
+
+### Pull request guidelines
+
+- Add unit tests, and remote tests to make sure we won't introduce regressions to your code later on.
+- Make sure CI passes for all Ruby versions and dependency versions we support.
+- XML handling: use `REXML` for parsing XML, and `builder` to generate it.
+- JSON: use the JSON module that is included in Rubys standard ibrary
+- HTTP: use `ActiveUtils`'s `PostsData`.
+- Do not add new gem dependencies.
+
+### Contributors
+
+- James MacAulay (<http://jmacaulay.net>)
+- Tobias Luetke (<http://blog.leetsoft.com>)
+- Cody Fauser (<http://codyfauser.com>)
+- Jimmy Baker (<http://jimmyville.com/>)
+- William Lang (<http://williamlang.net/>)
+- Cameron Fowler
+- Christopher Saunders (<http://christophersaunders.ca>)
+- Denis Odorcic
+- Dennis O'Connor
+- Dennis Theisen
+- Edward Ocampo-Gooding
+- Isaac Kearse
+- John Duff
+- Nigel Ramsay
+- Philip Arndt
+- Vikram Oberoi
+- Willem van Bergen

data/README.md

@@ -1,10 +1,9 @@
-# Active Shipping
-
-[![Build Status](https://travis-ci.org/Shopify/active_shipping.png)](https://travis-ci.org/Shopify/active_shipping)
+# ActiveShipping [![Build status](https://travis-ci.org/Shopify/active_shipping.svg?branch=master)](https://travis-ci.org/Shopify/active_shipping)
 
 This library interfaces with the web services of various shipping carriers. The goal is to abstract the features that are most frequently used into a pleasant and consistent Ruby API.
 
 - Finding shipping rates
+- Registering shipments
 - Tracking shipments
 
 Active Shipping is currently being used and improved in a production environment for [Shopify][]. Development is being done by the Shopify integrations team (<integrations-team@shopify.com>). Discussion is welcome in the [Active Merchant Google Group][discuss].
@@ -100,7 +99,7 @@ Active Shipping is currently being used and improved in a production environment
 
 After installing dependencies with `bundle install`, you can run the unit tests with `rake test:units` and the remote tests with `rake test:remote`. The unit tests mock out requests and responses so that everything runs locally, while the remote tests actually hit the carrier servers. For the remote tests, you'll need valid test credentials for any carriers' tests you want to run. The credentials should go in ~/.active_shipping/credentials.yml, and the format of that file can be seen in the included [credentials.yml](https://github.com/Shopify/active_shipping/blob/master/test/credentials.yml).
 
-## Contributing
+## Development
 
 Yes, please! Take a look at the tests and the implementation of the Carrier class to see how the basics work. At some point soon there will be a carrier template generator along the lines of the gateway generator included in Active Merchant, but carrier.rb outlines most of what's necessary. The other main classes that would be good to familiarize yourself with are Location, Package, and Response.
 
@@ -116,7 +115,7 @@ To log requests and responses, just set the `logger` on your carrier class to so
 
 (This logging functionality is provided by the [`PostsData` module](https://github.com/Shopify/active_utils/blob/master/lib/active_utils/posts_data.rb) in the `active_utils` dependency.)
 
-After you've pushed your well-tested changes to your github fork, make a pull request and we'll take it from there!
+After you've pushed your well-tested changes to your github fork, make a pull request and we'll take it from there! For more information, see CONTRIBUTING.md.
 
 ## Legal Mumbo Jumbo
 

data/lib/active_shipping.rb

@@ -27,6 +27,9 @@ require 'active_support/core_ext/enumerable'
 require 'active_support/core_ext/class/attribute_accessors'
 require 'active_utils'
 
+require 'rexml/document'
+require 'nokogiri'
+
 require 'vendor/quantified/lib/quantified'
 require 'vendor/xml_node/lib/xml_node'
 

data/lib/active_shipping/carrier.rb

@@ -1,7 +1,22 @@
 module ActiveShipping
+
+  # Carrier is abstract the base class for all supported carriers.
+  #
+  # To implement support for a carrier, you should subclass this class and
+  # implement all the methods the carrier supports.
+  #
+  # @see #find_rates
+  # @see #create_shipment
+  # @see #find_tracking_info
+  #
+  # @!attribute test_mode
+  #   Whether to interact with the carrier's sandbox environment.
+  #   @return [Boolean]
+  #
+  # @!attribute last_request
+  #   The last request performed against the carrier's API.
+  #   @see #save_request
   class Carrier
-    include ActiveUtils::RequiresParameters
-    include ActiveUtils::PostsData
     include Quantified
 
     attr_reader :last_request
@@ -9,6 +24,9 @@ module ActiveShipping
     alias_method :test_mode?, :test_mode
 
     # Credentials should be in options hash under keys :login, :password and/or :key.
+    # @param options [Hash] The details needed to connect to the carrier's API.
+    # @option options [Boolean] :test Set this to true to connect to the carrier's
+    #   sandbox environment instead of the production environment.
     def initialize(options = {})
       requirements.each { |key| requires!(options, key) }
       @options = options
@@ -16,22 +34,59 @@ module ActiveShipping
       @test_mode = @options[:test]
     end
 
-    # Override to return required keys in options hash for initialize method.
-    def requirements
-      []
-    end
-
-    # Override with whatever you need to get the rates
+    # Asks the carrier for rate estimates for a given shipment.
+    #
+    # @note Override with whatever you need to get the rates from the carrier.
+    #
+    # @param origin [ActiveShipping::Location] Where the shipment will originate from.
+    # @param destination [ActiveShipping::Location] Where the package will go.
+    # @param packages [Array<ActiveShipping::Package>] The list of packages that will
+    #   be in the shipment.
+    # @param options [Hash] Carrier-specific parameters.
+    # @return [ActiveShipping::RateResponse] The response from the carrier, which
+    #   includes 0 or more rate estimates for different shipping products
     def find_rates(origin, destination, packages, options = {})
+      raise NotImplementedError, "#find_rates is not supported by #{self.class.name}."
     end
 
-    # Override with whatever you need to get a shipping label
+    # Registers a new shipment with the carrier, to get a tracking number and
+    # potentially shipping labels
+    #
+    # @note Override with whatever you need to register a shipment, and obtain
+    #   shipping labels if supported by the carrier.
+    #
+    # @param origin [ActiveShipping::Location] Where the shipment will originate from.
+    # @param destination [ActiveShipping::Location] Where the package will go.
+    # @param packages [Array<ActiveShipping::Package>] The list of packages that will
+    #   be in the shipment.
+    # @param options [Hash] Carrier-specific parameters.
+    # @return [ActiveShipping::ShipmentResponse] The response from the carrier. This
+    #   response should include a shipment identifier or tracking_number if successful,
+    #   and potentially shipping labels.
     def create_shipment(origin, destination, packages, options = {})
+      raise NotImplementedError, "#create_shipment is not supported by #{self.class.name}."
     end
 
-    # Validate credentials with a call to the API. By default this just does a find_rates call
-    # with the orgin and destination both as the carrier's default_location. Override to provide
-    # alternate functionality, such as checking for test_mode to use test servers, etc.
+    # Retrieves tracking information for a previous shipment
+    #
+    # @note Override with whatever you need to get a shipping label
+    #
+    # @param tracking_number [String] The unique identifier of the shipment to track.
+    # @param options [Hash] Carrier-specific parameters.
+    # @return [ActiveShipping::TrackingResponse] The response from the carrier. This
+    #   response should a list of shipment tracking events if successful.
+    def find_tracking_info(tracking_number, options = {})
+      raise NotImplementedError, "#find_tracking_info is not supported by #{self.class.name}."
+    end
+
+    # Validate credentials with a call to the API.
+    #
+    # By default this just does a `find_rates` call with the orgin and destination both as
+    # the carrier's default_location. Override to provide alternate functionality, such as
+    # checking for `test_mode` to use test servers, etc.
+    #
+    # @return [Boolean] Should return `true` if the provided credentials proved to work,
+    #   `false` otherswise.
     def valid_credentials?
       location = self.class.default_location
       find_rates(location, location, Package.new(100, [5, 15, 30]), :test => test_mode)
@@ -41,17 +96,27 @@ module ActiveShipping
       true
     end
 
+    # The maximum weight the carrier will accept.
+    # @return [Quantified::Mass]
     def maximum_weight
       Mass.new(150, :pounds)
     end
 
     protected
 
-    def node_text_or_nil(xml_node)
-      xml_node ? xml_node.text : nil
+    include ActiveUtils::RequiresParameters
+    include ActiveUtils::PostsData
+
+    # Returns the keys that are required to be passed to the options hash
+    # @note Override to return required keys in options hash for initialize method.
+    # @return [Array<Symbol>]
+    def requirements
+      []
     end
 
-    # Override in subclasses for non-U.S.-based carriers.
+    # The default location to use for {#valid_credentials?}.
+    # @note Override for non-U.S.-based carriers.
+    # @return [ActiveShipping::Location]
     def self.default_location
       Location.new( :country => 'US',
                     :state => 'CA',
@@ -63,11 +128,16 @@ module ActiveShipping
                     :fax => '1-310-275-8159')
     end
 
-    # Use after building the request to save for later inspection. Probably won't ever be overridden.
+    # Use after building the request to save for later inspection.
+    # @return [void]
     def save_request(r)
       @last_request = r
     end
 
+    # Calculates a timestamp that corresponds a given number if business days in the future
+    #
+    # @param [Integer] The number of business days from now.
+    # @return [DateTime] A timestamp, the provided number of business days in the future.
     def timestamp_from_business_day(days)
       return unless days
       date = DateTime.now.utc

data/lib/active_shipping/carriers/canada_post.rb

@@ -23,7 +23,8 @@ module ActiveShipping
     PostalOutlet = Struct.new(:sequence_no, :distance, :name, :business_name, :postal_address, :business_hours)
 
     URL = "http://sellonline.canadapost.ca:30000"
-    DOCTYPE = '<!DOCTYPE eparcel SYSTEM "http://sellonline.canadapost.ca/DevelopersResources/protocolV3/eParcel.dtd">'
+    DTD_NAME = 'eparcel'
+    DTD_URI  = "http://sellonline.canadapost.ca/DevelopersResources/protocolV3/eParcel.dtd"
 
     RESPONSE_CODES = {
      '1'     =>	"All calculation was done",
@@ -106,92 +107,96 @@ module ActiveShipping
 
     private
 
+    def generate_xml(&block)
+      builder = Nokogiri::XML::Builder.new do |xml|
+        xml.doc.create_internal_subset(DTD_NAME, nil, DTD_URI)
+        yield(xml)
+      end
+      builder.to_xml
+    end
+
     def build_rate_request(origin, destination, line_items = [], options = {})
-      line_items = [line_items] unless line_items.is_a?(Array)
-      origin = origin.is_a?(Location) ? origin : Location.new(origin)
+      line_items  = [line_items] unless line_items.is_a?(Array)
+      origin      = origin.is_a?(Location) ? origin : Location.new(origin)
       destination = destination.is_a?(Location) ? destination : Location.new(destination)
 
-      xml_request = XmlNode.new('eparcel') do |root_node|
-        root_node << XmlNode.new('language', @options[:french] ? 'fr' : 'en')
-        root_node << XmlNode.new('ratesAndServicesRequest') do |request|
-
-          request << XmlNode.new('merchantCPCID', @options[:login])
-          request << XmlNode.new('fromPostalCode', origin.postal_code)
-          request << XmlNode.new('turnAroundTime', options[:turn_around_time]) if options[:turn_around_time]
-          request << XmlNode.new('itemsPrice', dollar_amount(line_items.map(&:value).compact.sum))
-
-          # line items
-          request << build_line_items(line_items)
-
-          # delivery info
-          # NOTE: These tags MUST be after line items
-          request << XmlNode.new('city', destination.city)
-          request << XmlNode.new('provOrState', destination.province)
-          request << XmlNode.new('country', handle_non_iso_country_names(destination.country))
-          request << XmlNode.new('postalCode', destination.postal_code)
+      generate_xml do |xml|
+        xml.eparcel do
+          xml.language(@options[:french] ? 'fr' : 'en')
+          xml.ratesAndServicesRequest do
+            xml.merchantCPCID(@options[:login])
+            xml.fromPostalCode(origin.postal_code)
+            xml.turnAroundTime(options[:turn_around_time]) if options[:turn_around_time]
+            xml.itemsPrice(dollar_amount(line_items.map(&:value).compact.sum))
+
+            build_line_items(xml, line_items)
+
+            xml.city(destination.city)
+            xml.provOrState(destination.province)
+            xml.country(handle_non_iso_country_names(destination.country))
+            xml.postalCode(destination.postal_code)
+          end
         end
       end
-
-      DOCTYPE + xml_request.to_s
     end
 
     def parse_rate_response(response, origin, destination, options = {})
-      xml = REXML::Document.new(response)
+      xml = Nokogiri.XML(response)
       success = response_success?(xml)
       message = response_message(xml)
 
       rate_estimates = []
       boxes = []
       if success
-        xml.elements.each('eparcel/ratesAndServicesResponse/product') do |product|
-          service_name = (@options[:french] ? @@name_french : @@name) + " " + product.get_text('name').to_s
-          service_code = product.attribute('id').to_s
+        xml.xpath('eparcel/ratesAndServicesResponse/product').each do |product|
+          service_name = (@options[:french] ? @@name_french : @@name) + " " + product.at('name').text
+          service_code = product['id']
 
           rate_estimates << RateEstimate.new(origin, destination, @@name, service_name,
                                              :service_code => service_code,
-                                             :total_price => product.get_text('rate').to_s,
+                                             :total_price => product.at('rate').text,
                                              :currency => 'CAD',
-                                             :shipping_date => product.get_text('shippingDate').to_s,
-                                             :delivery_range => [product.get_text('deliveryDate').to_s] * 2
+                                             :shipping_date => product.at('shippingDate').text,
+                                             :delivery_range => [product.at('deliveryDate').text] * 2
           )
         end
 
-        boxes = xml.elements.collect('eparcel/ratesAndServicesResponse/packing/box') do |box|
+        boxes = xml.xpath('eparcel/ratesAndServicesResponse/packing/box').map do |box|
           b = Box.new
           b.packedItems = []
-          b.name = box.get_text('name').to_s
-          b.weight = box.get_text('weight').to_s.to_f
-          b.expediter_weight = box.get_text('expediterWeight').to_s.to_f
-          b.length = box.get_text('length').to_s.to_f
-          b.width = box.get_text('width').to_s.to_f
-          b.height = box.get_text('height').to_s.to_f
-          b.packedItems = box.elements.collect('packedItem') do |item|
+          b.name = box.at('name').text
+          b.weight = box.at('weight').text.to_f
+          b.expediter_weight = box.at('expediterWeight').text.to_f
+          b.length = box.at('length').text.to_f
+          b.width = box.at('width').text.to_f
+          b.height = box.at('height').text.to_f
+          b.packedItems = box.xpath('packedItem').map do |item|
             p = PackedItem.new
-            p.quantity = item.get_text('quantity').to_s.to_i
-            p.description = item.get_text('description').to_s
+            p.quantity = item.at('quantity').text.to_i
+            p.description = item.at('description').text
             p
           end
           b
         end
 
-        postal_outlets = xml.elements.collect('eparcel/ratesAndServicesResponse/nearestPostalOutlet') do |outlet|
+        postal_outlets = xml.xpath('eparcel/ratesAndServicesResponse/nearestPostalOutlet').map do |outlet|
           postal_outlet = PostalOutlet.new
-          postal_outlet.sequence_no    = outlet.get_text('postalOutletSequenceNo').to_s
-          postal_outlet.distance       = outlet.get_text('distance').to_s
-          postal_outlet.name           = outlet.get_text('outletName').to_s
-          postal_outlet.business_name  = outlet.get_text('businessName').to_s
+          postal_outlet.sequence_no    = outlet.at('postalOutletSequenceNo').text
+          postal_outlet.distance       = outlet.at('distance').text
+          postal_outlet.name           = outlet.at('outletName').text
+          postal_outlet.business_name  = outlet.at('businessName').text
 
           postal_outlet.postal_address = Location.new(
-            :address1     => outlet.get_text('postalAddress/addressLine').to_s,
-            :postal_code  => outlet.get_text('postalAddress/postal_code').to_s,
-            :city         => outlet.get_text('postalAddress/municipality').to_s,
-            :province     => outlet.get_text('postalAddress/province').to_s,
+            :address1     => outlet.at('postalAddress/addressLine').text,
+            :postal_code  => outlet.at('postalAddress/postal_code').text,
+            :city         => outlet.at('postalAddress/municipality').text,
+            :province     => outlet.at('postalAddress/province').text,
             :country      => 'Canada',
-            :phone_number => outlet.get_text('phoneNumber').to_s
+            :phone_number => outlet.at('phoneNumber').text
           )
 
           postal_outlet.business_hours = outlet.elements.collect('businessHours') do |hour|
-            { :day_of_week => hour.get_text('dayOfWeek').to_s, :time => hour.get_text('time').to_s }
+            { :day_of_week => hour.at('dayOfWeek').text, :time => hour.at('time').text }
           end
 
           postal_outlet
@@ -202,17 +207,17 @@ module ActiveShipping
     end
 
     def response_success?(xml)
-      return false unless xml.get_text('eparcel/error').nil?
+      return false unless xml.at('eparcel/error').nil?
 
-      value = xml.get_text('eparcel/ratesAndServicesResponse/statusCode').to_s
+      value = xml.at('eparcel/ratesAndServicesResponse/statusCode').text
       value == '1' || value == '2'
     end
 
     def response_message(xml)
       if response_success?(xml)
-        xml.get_text('eparcel/ratesAndServicesResponse/statusMessage').to_s
+        xml.at('eparcel/ratesAndServicesResponse/statusMessage').text
       else
-        xml.get_text('eparcel/error/statusMessage').to_s
+        xml.at('eparcel/error/statusMessage').text
       end
     end
 
@@ -225,17 +230,17 @@ module ActiveShipping
     # <!--   - description (mandatory)      -->
     # <!--   - ready to ship (optional)     -->
 
-    def build_line_items(line_items)
-      XmlNode.new('lineItems') do |line_items_node|
+    def build_line_items(xml, line_items)
+      xml.lineItems do
         line_items.each do |line_item|
-          line_items_node << XmlNode.new('item') do |item|
-            item << XmlNode.new('quantity', 1)
-            item << XmlNode.new('weight', line_item.kilograms)
-            item << XmlNode.new('length', line_item.cm(:length).to_s)
-            item << XmlNode.new('width', line_item.cm(:width).to_s)
-            item << XmlNode.new('height', line_item.cm(:height).to_s)
-            item << XmlNode.new('description', line_item.options[:description] || ' ')
-            item << XmlNode.new('readyToShip', line_item.options[:ready_to_ship] || nil)
+          xml.item do
+            xml.quantity(1)
+            xml.weight(line_item.kilograms)
+            xml.length(line_item.cm(:length).to_s)
+            xml.width(line_item.cm(:width).to_s)
+            xml.height(line_item.cm(:height).to_s)
+            xml.description(line_item.options[:description] || ' ')
+            xml.readyToShip(line_item.options[:ready_to_ship] || nil)
             # By setting the 'readyToShip' tag to true, Sell Online will not pack this item in the boxes defined in the merchant profile.
           end
         end