trackerific 0.3.1 → 0.3.2

data/lib/ups.rb

@@ -5,24 +5,23 @@ module Trackerific
   
   # Provides package tracking support for UPS.
   class UPS < Base
+    # setup HTTParty
     include ::HTTParty
     format :xml
+    # use the test site for Rails development, production for everything else
     base_uri defined?(Rails) ? case Rails.env
       when 'test','development' then 'https://wwwcie.ups.com/ups.app/xml'
       when 'production' then 'https://www.ups.com/ups.app/xml'
     end : 'https://www.ups.com/ups.app/xml'
     
-    # The required options for tracking a UPS package are :key, :user_id, and
-    # :password.
-    #
-    # @return [Array] the required options for tracking a UPS package.
-    def required_options
-      [:key, :user_id, :password]
-    end
-    
-    # Tracks a UPS package.
-    # A Trackerific::Error is raised when a package cannot be tracked.
+    # Tracks a UPS package
+    # @param [String] package_id the package identifier
     # @return [Trackerific::Details] the tracking details
+    # @raise [Trackerific::Error] raised when the server returns an error (invalid credentials, tracking package, etc.)
+    # @example Track a package
+    #   ups = Trackerific::UPS.new key: 'api key', user_id: 'user', password: 'secret'
+    #   details = ups.track_package("1Z12345E0291980793")
+    # @api public
     def track_package(package_id)
       super
       # connect to UPS via HTTParty
@@ -40,8 +39,16 @@ module Trackerific
     
     protected
     
+    # The required options for tracking a UPS package
+    # @return [Array] the required options for tracking a UPS package.
+    # @api private
+    def required_options
+      [:key, :user_id, :password]
+    end
+    
     # Parses the response from UPS
     # @return [Trackerific::Details]
+    # @api private
     def parse_success_response(http_response)
       # get the activity from the UPS response
       activity = http_response['TrackResponse']['Shipment']['Package']['Activity']
@@ -70,14 +77,16 @@ module Trackerific
       )
     end
     
-    # Parses a UPS tracking response, and returns any errors.
+    # Parses a UPS tracking response, and returns any errors
     # @return [String] the UPS tracking error
+    # @api private
     def parse_error_response(http_response)
       http_response['TrackResponse']['Response']['Error']['ErrorDescription']
     end
     
-    # Builds the XML request to send to UPS for tracking a package.
+    # Builds the XML request to send to UPS for tracking a package
     # @return [String] the XML request
+    # @api private
     def build_xml_request
       xml = ""
       builder = ::Builder::XmlMarkup.new(:target => xml)

data/lib/usps.rb

@@ -6,34 +6,35 @@ module Trackerific
   
   # Provides package tracking support for USPS.
   class USPS < Base
+    # setup HTTParty
     include HTTParty
     format :xml
+    # use the test site for Rails development, production for everything else
     base_uri defined?(Rails) ? case Rails.env
       when 'test', 'development' then 'http://testing.shippingapis.com'
       when 'production' then 'https://secure.shippingapis.com'
     end : 'https://secure.shippingapis.com'
     
-    def initialize(options = {})
-      super
-      @options = options
-    end
-    
-    # The required option for tracking a UPS package is :user_id
-    #
-    # @return [Array] the required options for tracking a UPS package.
-    def required_options
-      [:user_id]
-    end
-    
-    # Tracks a USPS package.
-    # A Trackerific::Error is raised when a package cannot be tracked.
+    # Tracks a USPS package
+    # @param [String] package_id the package identifier
     # @return [Trackerific::Details] the tracking details
+    # @raise [Trackerific::Error] raised when the server returns an error (invalid credentials, tracking package, etc.)
+    # @example Track a package
+    #   usps = Trackerific::USPS.new user_id: 'user'
+    #   details = ups.track_package("EJ958083578US")
+    # @api public    
     def track_package(package_id)
       super
+      # connect to the USPS shipping API via HTTParty
       response = self.class.get('/ShippingAPITest.dll', :query => {:API => 'TrackV2', :XML => build_xml_request}.to_query)
+      # throw any HTTP errors
       response.error! unless response.code == 200
+      # raise a Trackerific::Error if there is an error in the response, or if the
+      # tracking response is malformed
       raise Trackerific::Error, response['Error']['Description'] unless response['Error'].nil?
       raise Trackerific::Error, "Tracking information not found in response from server." if response['TrackResponse'].nil?
+      # get the tracking information from the response, and convert into a
+      # Trackerific::Details
       tracking_info = response['TrackResponse']['TrackInfo']
       details = []
       tracking_info['TrackDetail'].each do |d|
@@ -47,6 +48,7 @@ module Trackerific
         desc = d[4..d.length].join(" ")
         details << Trackerific::Event.new(date, desc, "")
       end
+      # return the details
       Trackerific::Details.new(
         tracking_info['ID'],
         tracking_info['TrackSummary'],
@@ -56,15 +58,26 @@ module Trackerific
     
     protected
     
-    # Parses the response from UPS
-    # @return [Trackerific::Details]
+    # The required options for tracking a UPS package
+    # @return [Array] the required options for tracking a UPS package.
+    # @api private
+    def required_options
+      [:user_id]
+    end
+    
+    # Builds an XML request to send to USPS
+    # @return [String] the xml request
+    # @api private
     def build_xml_request
-      tracking_request = ""
-      builder = ::Builder::XmlMarkup.new(:target => tracking_request)
+      xml = ""
+      # set up the Builder
+      builder = ::Builder::XmlMarkup.new(:target => xml)
+      # build the request
       builder.TrackRequest(:USERID => @options[:user_id]) do |t|
         t.TrackID(:ID => @package_id)
       end
-      return tracking_request
+      # return the XML
+      xml
     end
     
   end

data/spec/lib/trackerific_spec.rb

@@ -11,13 +11,7 @@ describe 'Trackerific::Base' do
   before(:all) do
     @base = Trackerific::Base.new
   end
-  
-  describe :required_options do
-    it "should return an Array" do
-      @base.required_options().should be_kind_of Array
-    end
-  end
-  
+
   describe "tracking_service" do
     include Trackerific
     context "when given a UPS tracking number" do

data/trackerific.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{trackerific}
-  s.version = "0.3.1"
+  s.version = "0.3.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Travis Haynes"]
@@ -18,9 +18,6 @@ Gem::Specification.new do |s|
   ]
   s.files = [
     ".rspec",
-    ".yardoc/checksums",
-    ".yardoc/objects/root.dat",
-    ".yardoc/proxy_types",
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
@@ -100,7 +97,8 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<bundler>, [">= 1.0.13"])
       s.add_development_dependency(%q<jeweler>, [">= 1.5.2"])
       s.add_development_dependency(%q<rspec-rails>, [">= 2.6.1"])
-      s.add_development_dependency(%q<ruby-debug19>, [">= 0"])
+      s.add_development_dependency(%q<ruby-debug19>, [">= 0.11.6"])
+      s.add_development_dependency(%q<yardstick>, [">= 0.4.0"])
     else
       s.add_dependency(%q<rails>, [">= 3.0.0"])
       s.add_dependency(%q<httparty>, [">= 0.7.7"])
@@ -108,7 +106,8 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<bundler>, [">= 1.0.13"])
       s.add_dependency(%q<jeweler>, [">= 1.5.2"])
       s.add_dependency(%q<rspec-rails>, [">= 2.6.1"])
-      s.add_dependency(%q<ruby-debug19>, [">= 0"])
+      s.add_dependency(%q<ruby-debug19>, [">= 0.11.6"])
+      s.add_dependency(%q<yardstick>, [">= 0.4.0"])
     end
   else
     s.add_dependency(%q<rails>, [">= 3.0.0"])
@@ -117,7 +116,8 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<bundler>, [">= 1.0.13"])
     s.add_dependency(%q<jeweler>, [">= 1.5.2"])
     s.add_dependency(%q<rspec-rails>, [">= 2.6.1"])
-    s.add_dependency(%q<ruby-debug19>, [">= 0"])
+    s.add_dependency(%q<ruby-debug19>, [">= 0.11.6"])
+    s.add_dependency(%q<yardstick>, [">= 0.4.0"])
   end
 end
 

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 3
-  - 1
-  version: 0.3.1
+  - 2
+  version: 0.3.2
 platform: ruby
 authors: 
 - Travis Haynes
@@ -116,10 +116,27 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 0
-        version: "0"
+        - 11
+        - 6
+        version: 0.11.6
   type: :development
   prerelease: false
   version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: yardstick
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 4
+        - 0
+        version: 0.4.0
+  type: :development
+  prerelease: false
+  version_requirements: *id008
 description: Trackerific provides USPS, FedEx and UPS package tracking to Rails.
 email: travis.j.haynes@gmail.com
 executables: []
@@ -131,9 +148,6 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - .rspec
-- .yardoc/checksums
-- .yardoc/objects/root.dat
-- .yardoc/proxy_types
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -198,7 +212,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -53613295
+      hash: 154150799
       segments: 
       - 0
       version: "0"

data/.yardoc/checksums

@@ -1,6 +0,0 @@
-lib/ups.rb 2b98972c48bd4032d5a6cd2017549ce394e8ea0d
-lib/usps.rb b6e83100cd5225341ce5a61f0ff843440309e063
-lib/fedex.rb ba42d502349530fe2518303c23d2b8babecd5f2d
-lib/trackerific.rb 78b145e898c315d3e80aaef686877cb674621fed
-lib/trackerific_event.rb 21e48404ba7b8b90114ce0d74d38248a637a0452
-lib/trackerific_details.rb d3c5cc1844259f2889b4d82920b12ad57fe4d412