trackerific 0.5.5 → 0.6.0

data/README.rdoc

@@ -18,10 +18,20 @@ configure your credentials for each service.
   # config/initializers/trackerific.rb
   require 'trackerific'
   Trackerific.configure do |config|
-    config.fedex :account => 'account', :meter => '123456789'
-    config.ups :key => 'key', :user_id => 'userid', :password => 'secret'
-    config.usps :user_id => 'userid'
+    config.fedex  :account  => 'account',
+                  :meter    => '123456789'
+    
+    config.ups    :key      => 'key',
+                  :user_id  => 'userid',
+                  :password => 'secret'
+    
+    config.usps   :user_id  => 'userid',
+                  :use_city_state_lookup => true
   end
+  
+For USPS packages, the option :use_city_state_lookup defaults to false, and will
+only work if you have access to USPS's CityStateLookup API. If you can enable
+it, this feature will provide the location for USPS package events.
 
 === Tracking with Automatic Service Discovery
 
@@ -85,6 +95,14 @@ Note that events.last will return the first event the tracking provider
 supplied. This is because the events are listed in LIFO order, so the most
 recent events will always be at the top of the list.
 
+=== City / State Lookup Via USPS
+
+If you have access to the USPS CityStateLookup API, you can use Trackerific to
+look up the city and state of a zipcode.
+
+  usps = Trackerific::USPS.new :user_id => 'userid'
+  usps.city_state_lookup "90210" # => { :city => 'BEVERLY HILLS', :state => 'CA', :zip => '90210' }
+
 === Exception handling
 
 Exception handling is esssential for tracking packages. If, for example,
@@ -98,60 +116,60 @@ example on how to handle Trackerific::Errors:
     puts e.message
   end
 
-== Extending
+or for a Rails application:
+
+  # in app/controllers/application_controller.rb
+  rescue_from Trackerific::Error do |exception|
+    redirect_to root_url, :alert => exception.message
+  end
+
+== Writing a Custom Service
 
-Here is a basic outline of a custom Trackerific service.
+Here is a spec for writing a custom trackerific service:
 
-lib/trackerific/services/my_tracking_service.rb:
-  module Trackerific
-    class MyTrackingService < Trackerific::Base
-      def self.required_options
-        # any options your service requires. these are usually user credentials
-        [ :some, :options ]
+  describe Trackerific::CustomService do
+    specify("it should descend from Trackerific::Service") {
+      Trackerific::CustomService.superclass.should be Trackerific::Service
+    }
+    describe :track_package do
+      before do
+        @valid_package_id = 'valid package id'
+        @invalid_package_id = 'invalid package id'
+        @service = Trackerific::CustomService.new :required => 'option'
       end
-      def self.package_id_matchers
-        # write some custom regex matchers for your tracking package IDs
-        [ /^[0-9]{15}$/ ] # fedex package matcher
+      context "with a successful response from the server" do
+        before(:each) do
+          @tracking = @service.track_package(@valid_package_id)
+        end
+        subject { @tracking }
+        it("should return a Trackerific::Details") { should be_a Trackerific::Details }
+        describe :summary do
+          subject { @tracking.summary }
+          it { should_not be_empty }
+        end
       end
-      def track_package(package_id)
-        # implement your tracking code here
-        Trackerific::Details.new(
-          "summary",
-          [
-            Trackerific::Event.new(Time.now, "description", "location"),
-            Trackerific::Event.new(Time.now, "description", "location")
-          ]
-        )
+      context "with an error response from the server" do
+        specify { lambda { @service.track_package(@invalid_package_id) }.should raise_error(Trackerific::Error) }
       end
     end
-  end
-
-spec/lib/trackerific/services/my_tracking_service_spec.rb:
-  describe "Trackerific::MyTrackingService" do
     describe :required_options do
-      subject { Trackerific::MyTrackingService.required_options }
-      it { should include(:some) }
-      it { should include(:options) }
+      subject { Trackerific::CustomService.required_options }
+      it { should include(:required) }
     end
-    describe :package_id_matchers do
-      it "should be an Array of Regexp" do
-        Trackerific::MyTrackingService.package_id_matchers.should each { |m| m.should be_a Regexp }
+    describe :valid_options do
+      it "should include required_options" do
+        valid = Trackerific::CustomService.valid_options
+        Trackerific::CustomService.required_options.each do |opt|
+          valid.should include opt
+        end
       end
     end
-    describe :track_package do
-      pending "your track_package specs"
+    describe :package_id_matchers do
+      subject { Trackerific::CustomService.package_id_matchers }
+      it("should be an Array of Regexp") { should each { |m| m.should be_a Regexp } }
     end
   end
 
-Please make sure to include comments, documentation, and specs for your service.
-Trackerific uses {RSpec}[https://github.com/dchelimsky/rspec] for tests,
-{simplecov}[https://github.com/colszowka/simplecov] for code coverage,
-and {Yardoc}[http://yardoc.org/] for documentation. You can also take advantage
-of {yardstick}[https://github.com/dkubb/yardstick] to help verify the coverage
-of the comments of your code. You can use the rake task:
-  rake yardstick_measure
-which will generate a measurement/report.txt file.
-
 === Testing with Trackerific
 
 Trackerific provides a mocked service you can use in your unit tests of your

data/Rakefile

@@ -16,7 +16,7 @@ Jeweler::Tasks.new do |gem|
   gem.homepage = "http://github.com/travishaynes/trackerific"
   gem.license = "MIT"
   gem.summary = %Q{Trackerific provides package tracking to Rails.}
-  gem.description = %Q{Trackerific provides USPS, FedEx and UPS package tracking to Rails.}
+  gem.description = %Q{Package tracking made easy for Rails. Currently supported services include FedEx, UPS, and USPS.}
   gem.email = "travis.j.haynes@gmail.com"
   gem.authors = ["Travis Haynes"]
   gem.rubyforge_project = "trackerific"

data/VERSION

@@ -1 +1 @@
-0.5.5
+0.6.0

data/changelog

@@ -0,0 +1,9 @@
+Mon Jun 27 2011 - Travis Haynes <travis.j.haynes@gmail.com>
+
+ * Added support for USPS City / State API for looking up a city and state by
+its zipcode.
+ * Renamed required_options to required_parameters. (Makes much more sense.)
+ * Added a lot more specs for more code coverage.
+ * Changed the way that Details and Events are initialized. Using options
+instead of parameters.
+ * Removed doc folder from git, since it is automatically generated with yard

data/lib/trackerific/configuration.rb

@@ -18,8 +18,8 @@ module Trackerific
       unless args.empty?
         # Only accept Hashes
         raise ArgumentError unless args[0].class == Hash
-        # Validate configuration values against the required options for that service
-        validate_options args[0], Trackerific.service_get(sym).required_options
+        # Validate configuration values against the required parameters for that service
+        validate_options args[0], Trackerific.service_get(sym).required_parameters
         # Store the configuration options
         @options[sym] = args[0]
       end

data/lib/trackerific/details.rb

@@ -2,18 +2,23 @@ module Trackerific
   # Details returned when tracking a package. Stores the package identifier,
   # a summary, and the events.
   class Details
+    include OptionsHelper
+    
     # Provides a new instance of Details
-    # @param [String] package_id the package identifier
-    # @param [String] summary a summary of the tracking status
-    # @param [Array, Trackerific::Event] events the tracking events
+    # @param [Hash] details The details for this package
     # @api private
-    def initialize(package_id, summary, events)
-      @package_id = package_id
-      @summary = summary
-      @events = events
+    def initialize(details = {})
+      required = [:package_id, :summary, :events]
+      valid = required + [:weight, :via]
+      validate_options(details, required, valid)
+      @package_id = details[:package_id]
+      @summary = details[:summary]
+      @events = details[:events]
+      @weight = details[:weight] || nil
+      @via = details[:via] || nil
     end
     
-    # Read-only string for the package identifier
+    # The package identifier
     # @example Get the id of a tracked package
     #   details.package_id # => the package identifier
     # @return [String] the package identifier
@@ -22,7 +27,7 @@ module Trackerific
       @package_id
     end
     
-    # Read-only string for the summary of the package's tracking events
+    # Summary of the package's tracking events
     # @example Get the summary of a tracked package
     #   details.summary # => Summary of the tracking events (i.e. Delivered)
     # @return [String] a summary of the tracking status
@@ -31,7 +36,7 @@ module Trackerific
       @summary
     end
     
-    # Read-only string for the events for this package
+    # The events for this package
     # @example Print all the events for a tracked package
     #   puts details.events
     # @example Get the date the package was shipped
@@ -45,5 +50,26 @@ module Trackerific
     def events
       @events
     end
+    
+    # The weight of the package (may not be supported by all services)
+    # @example Get the weight of a package
+    #   details.weight[:weight] # => the weight
+    #   details.weight[:units]  # => the units of measurement for the weight (i.e. "LBS")
+    # @return [Hash] Example: { units: 'LBS', weight: 19.1 }
+    # @api public
+    def weight
+      @weight
+    end
+    
+    # Example: UPS 2ND DAY AIR. May not be supported by all services
+    # @example Get how the package was shipped
+    #   ups = Trackerific::UPS.new :user_id => "userid"
+    #   details = ups.track_package "1Z12345E0291980793"
+    #   details.via # => "UPS 2ND DAY AIR"
+    # @return [String] The service used to ship the package
+    # @api public
+    def via
+      @via
+    end
   end
 end

data/lib/trackerific/event.rb

@@ -1,15 +1,17 @@
 module Trackerific
   # Provides details for a tracking event
   class Event
+    include OptionsHelper
+    
     # Provides a new instance of Event
-    # @param [DateTime] date the date / time of the event
-    # @param [String] description the event's description
-    # @param [String] location where the event took place
+    # @param [Hash] details The details of the event
     # @api private
-    def initialize(date, description, location)
-      @date = date
-      @description = description
-      @location = location
+    def initialize(details = {})
+      required_details = [:date, :description, :location]
+      validate_options details, required_details
+      @date         = details[:date]
+      @description  = details[:description]
+      @location     = details[:location]
     end
     
     # The date and time of the event

data/lib/trackerific/service.rb

@@ -3,10 +3,10 @@ module Trackerific
   class Service
     include OptionsHelper
     
-    # Creates a new instance of Trackerific::Service with required options
+    # Creates a new instance of Trackerific::Service
     # @api private
     def initialize(options = {})
-      validate_options options, self.class.required_options
+      validate_options options, self.class.required_parameters, self.class.valid_options
       @options = options
     end
     
@@ -48,21 +48,37 @@ module Trackerific
       end
       
       # An array of options that are required to create a new instance of this class
-      # @return [Array] the required options
+      # @return [Array] the required parameters
       # @example Override this method in your custom tracking service to enforce some options
       #   module Trackerific
       #     class MyTrackingService < Service
-      #       def self.required_options
+      #       def self.required_parameters
       #         [:all, :these, :are, :required]
       #       end
       #     end
       #   end
       # @api semipublic
-      def required_options
+      def required_parameters
         []
       end
       
-      # Provides a humanized string that provides the name of the service (i.e. "FedEx")
+      # An array of valid options used for creating this class
+      # @return [Array] the valid options
+      # @example Override this method in your custom tracking service to add options
+      #   module Trackerific
+      #     class MyTrackingService < Service
+      #       def self.valid_options
+      #         # NOTE: make sure to include the required parameters in this list!
+      #         required_parameters + [:some, :more, :options]
+      #       end
+      #     end
+      #   end
+      # @api semipublic
+      def valid_options
+        required_parameters + []
+      end
+      
+      # Provides a humanized string that provides the name of the service
       # @return [String] the service name
       # @note This defaults to using the class name.
       # @example Override this method in your custom tracking service to provide a name

data/lib/trackerific/services/fedex.rb

@@ -17,11 +17,11 @@ module Trackerific
         [ /^[0-9]{15}$/ ]
       end
       
-      # Returns an Array of required options used when creating a new instance
-      # @return [Array] required options for tracking a FedEx package are :account
+      # Returns an Array of required parameters used when creating a new instance
+      # @return [Array] required parameters for tracking a FedEx package are :account
       #   and :meter
       # @api private
-      def required_options
+      def required_parameters
         [:account, :meter]
       end
     end
@@ -52,13 +52,17 @@ module Trackerific
         date = Time.parse("#{e["Date"]} #{e["Time"]}")
         desc = e["Description"]
         addr = e["Address"]
-        events << Trackerific::Event.new(date, desc, "#{addr["StateOrProvinceCode"]} #{addr["PostalCode"]}")
+        events << Trackerific::Event.new(
+          :date         => date,
+          :description  => desc,
+          :location     => "#{addr["StateOrProvinceCode"]} #{addr["PostalCode"]}"
+        )
       end
       # Return a Trackerific::Details containing all the events
       Trackerific::Details.new(
-        details["TrackingNumber"],
-        details["StatusDescription"],
-        events
+        :package_id => details["TrackingNumber"],
+        :summary    => details["StatusDescription"],
+        :events     => events
       )
     end
     

data/lib/trackerific/services/mock_service.rb

@@ -10,17 +10,14 @@ module Trackerific
       # @return [Array, Regexp] the regular expression
       # @api private
       def package_id_matchers
-        if defined?(Rails)
-          return [ /XXXXXXXXXX/, /XXXxxxxxxx/ ] unless Rails.env.production?
-        else
-          return [ ] # no matchers in production mode
-        end
+        return [ /XXXXXXXXXX/, /XXXxxxxxxx/ ] unless Rails.env.production?
+        return [ ]
       end
       
-      # Returns an Array of required options used when creating a new instance
-      # @return [Array] required options
+      # Returns an Array of required parameters used when creating a new instance
+      # @return [Array] required parameters
       # @api private
-      def required_options
+      def required_parameters
         [ ]
       end
     end
@@ -38,12 +35,24 @@ module Trackerific
       super
       if package_id == "XXXXXXXXXX"
         Trackerific::Details.new(
-          package_id,
-          "Your package was delivered.",
-          [
-            Trackerific::Event.new(Date.today, "Package delivered.", "SANTA MARIA, CA"),
-            Trackerific::Event.new(Date.today - 1, "Package scanned.", "SANTA BARBARA, CA"),
-            Trackerific::Event.new(Date.today - 2, "Package picked up for delivery.", "LOS ANGELES, CA")
+          :package_id => package_id,
+          :summary    => "Your package was delivered.",
+          :events     => [
+            Trackerific::Event.new(
+              :date         => Date.today,
+              :description  => "Package delivered.",
+              :location     => "SANTA MARIA, CA"
+            ),
+            Trackerific::Event.new(
+              :date         => Date.today - 1,
+              :description  => "Package scanned.",
+              :location     => "SANTA BARBARA, CA"
+            ),
+            Trackerific::Event.new(
+              :date         => Date.today - 2,
+              :description  => "Package picked up for delivery.",
+              :location     => "LOS ANGELES, CA"
+            )
           ]
         )
       else

data/lib/trackerific/services/ups.rb

@@ -21,10 +21,10 @@ module Trackerific
       def package_id_matchers
         [ /^.Z/, /^[HK].{10}$/ ]
       end    
-      # The required options for tracking a UPS package
-      # @return [Array] the required options for tracking a UPS package
+      # The required parameters for tracking a UPS package
+      # @return [Array] the required parameters for tracking a UPS package
       # @api private
-      def required_options
+      def required_parameters
         [:key, :user_id, :password]
       end
     end
@@ -64,7 +64,7 @@ module Trackerific
       activity = [activity] if activity.is_a? Hash
       # UPS does not provide a summary, so we'll just use the last tracking status
       summary = activity.first['Status']['StatusType']['Description'].titleize
-      details = []
+      events = []
       activity.each do |a|
         # the time format from UPS is HHMMSS, which cannot be directly converted
         # to a Ruby time.
@@ -75,13 +75,17 @@ module Trackerific
         date    = DateTime.parse("#{date} #{hours}:#{minutes}:#{seconds}")
         desc    = a['Status']['StatusType']['Description'].titleize
         loc     = a['ActivityLocation']['Address'].map {|k,v| v}.join(" ")
-        details << Trackerific::Event.new(date, desc, loc)
+        events << Trackerific::Event.new(
+          :date         => date,
+          :description  => desc,
+          :location     => loc
+        )
       end
       
       Trackerific::Details.new(
-        @package_id,
-        summary,
-        details
+        :package_id => @package_id,
+        :summary    => summary,
+        :events     => events
       )
     end
     

data/lib/trackerific/services/usps.rb

@@ -1,4 +1,5 @@
 require 'date'
+require 'active_support/core_ext/object/to_query'
 
 module Trackerific
   require 'builder'
@@ -19,12 +20,19 @@ module Trackerific
         [ /^E\D{1}\d{9}\D{2}$|^9\d{15,21}$/ ]
       end    
       
-      # The required options for tracking a UPS package
-      # @return [Array] the required options for tracking a UPS package
+      # The required parameters for tracking a UPS package
+      # @return [Array] the required parameters for tracking a UPS package
       # @api private
-      def required_options
+      def required_parameters
         [:user_id]
       end
+      
+      # List of all valid options for tracking a UPS package
+      # @return [Array] the valid options for tracking a UPS package
+      # @api private
+      def valid_options
+        required_parameters + [:use_city_state_lookup]
+      end
     end
     
     # Tracks a USPS package
@@ -42,44 +50,129 @@ module Trackerific
         Rails.env.production? ? "/ShippingAPI.dll" : "/ShippingAPITest.dll",
         :query => {
           :API => 'TrackV2',
-          :XML => build_xml_request
+          :XML => build_tracking_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?
+      # raise any errors
+      error = check_response_for_errors(response, :TrackV2)
+      raise error unless error.nil?
       # get the tracking information from the response, and convert into a
       # Trackerific::Details
       tracking_info = response['TrackResponse']['TrackInfo']
-      details = []
+      events = []
+      # check if we should look up the exact location of the details
+      use_city_state_lookup = @options[:use_city_state_lookup] || false
+      # parse the details
       tracking_info['TrackDetail'].each do |d|
         # each tracking detail is a string in this format:
-        # MM DD HH:MM am/pm DESCRIPTION CITY STATE ZIP.
-        # unfortunately, it will not be possible to tell the difference between
-        # the location, and the summary. So, for USPS, the location will be in
-        # the summary
+        # MM DD HH:MM am/pm DESCRIPTION CITY STATE ZIP
         d = d.split(" ")
         date = DateTime.parse(d[0..3].join(" "))
         desc = d[4..d.length].join(" ")
-        details << Trackerific::Event.new(date, desc, "")
+        # the zip code is always the last word, if it is all numbers
+        if use_city_state_lookup then
+          # this gets the exact location of the package, and is very accurate,
+          # however, it requires access to the shipping services in USPS
+          zip = d[d.length-1]
+          loc = ""
+          # check if zip is a number
+          if zip.to_i.to_s == zip
+            loc = city_state_lookup(zip)
+            loc = "#{loc[:city].titelize}, #{loc[:state]} #{loc[:zip]}"
+            # attempt to delete the location from the description
+            desc = desc.gsub("#{loc[:city]} #{loc[:state]} #{loc[:zip]}", "")
+          end
+        else
+          # extract the location from the description - not always accurate,
+          # but better than nothing
+          d = desc.split(" ") # => ['the', 'description', 'city', 'state', 'zip']
+          desc = d[0..d.length-4].join(" ") # => "the description"
+          loc = d[d.length-3, d.length] # => ['city', 'state', 'zip']
+          loc = "#{loc[0].titleize}, #{loc[1]} #{loc[2]}" # "City, STATE zip"
+        end
+        events << Trackerific::Event.new(
+          :date         => date,
+          :description  => desc.capitalize,
+          :location     => loc
+        )
       end unless tracking_info['TrackDetail'].nil?
       # return the details
       Trackerific::Details.new(
-        tracking_info['ID'],
-        tracking_info['TrackSummary'],
-        details
+        :package_id => tracking_info['ID'],
+        :summary    => tracking_info['TrackSummary'],
+        :events     => events
       )
     end
     
+    # Gets the city/state of a zipcode
+    # @param [String] zipcode The zipcode to find the city/state for
+    # @return [Hash] { zip: 'the zipcode, 'city: "the city", state: "the state" }
+    # @example Lookup zipcode for Beverly Hills, CA
+    #   usps = Trackerific::USPS.new :user_id => 'youruserid'
+    #   city_state = usps.city_state_lookup(90210)
+    #   city_state[:city]  # => BEVERLY HILLS
+    #   city_state[:state] # => CA
+    #   city_state[:zip]   # => 90210
+    # @api public
+    def city_state_lookup(zipcode)
+      response = self.class.get(
+        Rails.env.production? ? "/ShippingAPI.dll" : "/ShippingAPITest.dll",
+        :query => {
+          :API => 'CityStateLookup',
+          :XML => build_city_state_xml_request(zipcode)
+        }.to_query
+      )
+      # raise any errors
+      error = check_response_for_errors(response, :CityStateLookup)
+      raise error unless error.nil?
+      # return the city, state, and zip
+      response = response['CityStateLookupResponse']['ZipCode']
+      {
+        :city   => response['City'],
+        :state  => response['State'],
+        :zip    => response['Zip5']
+      }
+    end
+    
     protected
     
-    # Builds an XML request to send to USPS
+    # Checks a HTTParty response for USPS, or HTTP errors
+    # @param [HTTParty::Response] response The HTTParty response to check
+    # @return The exception to raise, or nil
+    # @api private
+    def check_response_for_errors(response, api)
+      # return any HTTP errors
+      return response.error unless response.code == 200
+      # return a Trackerific::Error if there is an error in the response, or if
+      # the tracking response is malformed
+      return Trackerific::Error.new(response['Error']['Description']) unless response['Error'].nil?
+      return Trackerific::Error.new("Tracking information not found in response from server.") if response['TrackResponse'].nil? && api == :TrackV2
+      return Trackerific::Error.new("City / state information not found in response from server.") if response['CityStateLookupResponse'].nil? && api == :CityStateLookup
+      return nil # no errors to report
+    end
+    
+    # Builds an XML city/state lookup request
+    # @param [String] zipcode The zipcode to find the city/state for
+    # @return [String] the xml request
+    # @api private
+    def build_city_state_xml_request(zipcode)
+      xml = ""
+      # set up the Builder
+      builder = ::Builder::XmlMarkup.new(:target => xml)
+      # add the XML header
+      builder.instruct! :xml, :version => "1.0", :encoding => "UTF-8"
+      # build the request
+      builder.CityStateLookupRequest(:USERID => @options[:user_id]) do |request|
+        request.ZipCode(:ID => "5") do |zip|
+          zip.Zip5 zipcode
+        end
+      end
+    end
+    
+    # Builds an XML tracking request
     # @return [String] the xml request
     # @api private
-    def build_xml_request
+    def build_tracking_xml_request
       xml = ""
       # set up the Builder
       builder = ::Builder::XmlMarkup.new(:target => xml)

data/spec/fixtures/usps_city_state_lookup_response.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<CityStateLookupResponse>
+  <ZipCode ID="0">
+    <Zip5>90210</Zip5>
+    <City>BEVERLY HILLS</City>
+    <State>CA</State>
+  </ZipCode>
+</CityStateLookupResponse>