trackerific 0.6.2 → 0.7.0

data/lib/trackerific/services/usps.rb

@@ -1,204 +1,200 @@
-require 'date'
 require 'active_support/core_ext/object/to_query'
+require 'httparty'
+require 'builder'
+require 'date'
 
 module Trackerific
-  require 'builder'
-  require 'httparty'
-  
-  # Provides package tracking support for USPS.
-  class USPS < Trackerific::Service
-    # setup HTTParty
-    include HTTParty
-    format :xml
-    base_uri Rails.env.production? ? "http://production.shippingapis.com" : "http://testing.shippingapis.com"
-    
-    class << self
+  module Services
+    # Provides package tracking support for USPS.
+    class USPS < Base
+      include HTTParty
+      format :xml
+
+      base_uri case (ENV['RAILS_ENV'] || 'production')
+      when 'production' then "http://production.shippingapis.com"
+      else "http://testing.shippingapis.com"
+      end
+
+      def initialize(options={})
+        @options = options
+      end
+
       # An Array of Regexp that matches valid USPS package IDs
       # @return [Array, Regexp] the regular expression
       # @api private
-      def package_id_matchers
+      def self.package_id_matchers
         [ /^E\D{1}\d{9}\D{2}$|^9\d{15,21}$/ ]
-      end    
-      
-      # The required parameters for tracking a UPS package
-      # @return [Array] the required parameters for tracking a UPS package
+      end
+
+      # 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(id)
+        @package_id = id
+        # connect to the USPS shipping API via HTTParty
+        response = self.class.get(
+          env == 'production' ? "/ShippingAPI.dll" : "/ShippingAPITest.dll",
+          query: { :API => 'TrackV2', :XML => build_tracking_xml_request }.to_query
+        )
+        # raise any errors
+        error = check_response_for_errors(response, :TrackV2)
+        raise error unless error.nil?
+        # get the tracking information from the response
+        tracking_info = response['TrackResponse']['TrackInfo']
+        events = []
+        # parse the tracking events out of the USPS tracking info
+        tracking_info['TrackDetail'].each do |d|
+          events << Trackerific::Event.new(
+            date_of_event(d),
+            description_of_event(d),
+            location_of_event(d)
+          )
+        end unless tracking_info['TrackDetail'].nil?
+        # return the details
+        Trackerific::Details.new(
+          tracking_info['ID'],
+          tracking_info['TrackSummary'],
+          events
+        )
+      end
+
+      # Gets the city/state of a zipcode - requires access to USPS address APIs
+      # @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(
+          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
+
+      private
+
+      def env
+        @rails_env ||= ENV['RAILS_ENV'] || 'production'
+      end
+
+      # Parses a USPS tracking event, and returns its date
+      # @param [String] event The tracking event to parse
+      # @return [DateTime] The date / time of the event
       # @api private
-      def required_parameters
-        [:user_id]
+      def date_of_event(event)
+        # get the date out of
+        # Mon DD HH:MM am/pm THE DESCRIPTION CITY STATE ZIP.
+        d = event.split(" ")
+        DateTime.parse(d[0..3].join(" "))
       end
-      
-      # List of all valid options for tracking a UPS package
-      # @return [Array] the valid options for tracking a UPS package
+
+      # Parses a USPS tracking event, and returns its description
+      # @param [String] event The tracking event to parse
+      # @return [DateTime] The description of the event
       # @api private
-      def valid_options
-        required_parameters + [:use_city_state_lookup]
+      def description_of_event(event)
+        # get the description out of
+        # Mon DD HH:MM am/pm THE DESCRIPTION CITY STATE ZIP.
+        d = event.split(" ")
+        d[4..d.length-4].join(" ").capitalize
       end
-    end
-    
-    # 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(
-        Rails.env.production? ? "/ShippingAPI.dll" : "/ShippingAPITest.dll",
-        :query => { :API => 'TrackV2', :XML => build_tracking_xml_request }.to_query
-      )
-      # raise any errors
-      error = check_response_for_errors(response, :TrackV2)
-      raise error unless error.nil?
-      # get the tracking information from the response
-      tracking_info = response['TrackResponse']['TrackInfo']
-      events = []
-      # parse the tracking events out of the USPS tracking info
-      tracking_info['TrackDetail'].each do |d|
-        events << Trackerific::Event.new(
-          :date         => date_of_event(d),
-          :description  => description_of_event(d).capitalize,
-          :location     => location_of_event(d)
-        )
-      end unless tracking_info['TrackDetail'].nil?
-      # return the details
-      Trackerific::Details.new(
-        :package_id => tracking_info['ID'],
-        :summary    => tracking_info['TrackSummary'],
-        :events     => events
-      )
-    end
-    
-    # Gets the city/state of a zipcode - requires access to USPS address APIs
-    # @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
-    
-    private
-    
-    # Parses a USPS tracking event, and returns its date
-    # @param [String] event The tracking event to parse
-    # @return [DateTime] The date / time of the event
-    # @api private
-    def date_of_event(event)
-      # get the date out of
-      # Mon DD HH:MM am/pm THE DESCRIPTION CITY STATE ZIP.
-      d = event.split(" ")
-      DateTime.parse(d[0..3].join(" "))
-    end
-    
-    # Parses a USPS tracking event, and returns its description
-    # @param [String] event The tracking event to parse
-    # @return [DateTime] The description of the event
-    # @api private
-    def description_of_event(event)
-      # get the description out of
-      # Mon DD HH:MM am/pm THE DESCRIPTION CITY STATE ZIP.
-      d = event.split(" ")
-      d[4..d.length-4].join(" ").capitalize
-    end
-    
-    # Parses a USPS tracking event, and returns its location
-    # @param [String] event The tracking event to parse
-    # @return The location of the event
-    # @api private
-    def location_of_event(event)
-      # remove periods, and split by spaces
-      d = event.gsub(".", "").split(" ")
-      l = d[d.length-3, d.length] # => ['city', 'state', 'zip']
-      # this is the location from the USPS tracking XML. it is not guaranteed
-      # to be completely accurate, since there's no way to know if it will
-      # always be the last 3 words.
-      city  = l[0]
-      state = l[1]
-      zip   = l[2]
-      # for greater accuracy, we can use the city/state lookup API from USPS
-      if @options[:use_city_state_lookup]
-        l = city_state_lookup(zip)
-        # these will be nil if USPS does not have the zipcode in their database
-        city  = l[:city]  unless l[:city].nil?
-        state = l[:state] unless l[:state].nil?
-        zip   = l[:zip]   unless l[:zip].nil?
+
+      # Parses a USPS tracking event, and returns its location
+      # @param [String] event The tracking event to parse
+      # @return The location of the event
+      # @api private
+      def location_of_event(event)
+        # remove periods, and split by spaces
+        d = event.gsub(".", "").split(" ")
+        l = d[d.length-3, d.length] # => ['city', 'state', 'zip']
+        # this is the location from the USPS tracking XML. it is not guaranteed
+        # to be completely accurate, since there's no way to know if it will
+        # always be the last 3 words.
+        city  = l[0]
+        state = l[1]
+        zip   = l[2]
+        # for greater accuracy, we can use the city/state lookup API from USPS
+        if @options[:use_city_state_lookup]
+          l = city_state_lookup(zip)
+          # these will be nil if USPS does not have the zipcode in their database
+          city  = l[:city]  unless l[:city].nil?
+          state = l[:state] unless l[:state].nil?
+          zip   = l[:zip]   unless l[:zip].nil?
+        end
+        "#{city}, #{state} #{zip}"
       end
-      "#{city.titleize}, #{state} #{zip}"
-    end
-    
-    # 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
+
+      # 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
-    end
-    
-    # Builds an XML tracking request
-    # @return [String] the xml request
-    # @api private
-    def build_tracking_xml_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)
+
+      # Builds an XML tracking request
+      # @return [String] the xml request
+      # @api private
+      def build_tracking_xml_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 the XML
+        xml
       end
-      # return the XML
-      xml
+
     end
-    
+
   end
-  
 end

data/lib/trackerific/services.rb

@@ -0,0 +1,41 @@
+module Trackerific
+  module Services
+    @services = {}
+
+    class << self
+      # Finds a service by the given name
+      # @param [Symbol] name The name of the service
+      # @return A descendant of Trackerific::Services::Base or nil for no match
+      # @api public
+      def [](name)
+        @services[name]
+      end
+
+      # Registers a service by the given name and class
+      # @param [Symbol] name The name of the service
+      # @param [Trackerific::Services::Base] _class The base class to register
+      # @api public
+      def []=(name, _class)
+        unless _class.superclass == Trackerific::Services::Base
+          raise ArgumentError,
+            "Expected a Trackerific::Services::Base, got #{_class.inspect}",
+            caller
+        end
+
+        @services[name] = _class
+      end
+
+      # Finds the tracking service(s) that are capable of tracking the given
+      # package ID
+      # @param [String] id The package identifier
+      # @return [Array, Trackerific::Services::Base] The services that are
+      # capable of tracking the given ID.
+      # @example Find out which service providers can track a FedEx ID
+      #   Trackerific::Services.find_by_package_id "183689015000001"
+      # @api public
+      def find_by_package_id(id)
+        @services.map {|n,s| s if s.can_track?(id) }.compact
+      end
+    end
+  end
+end

data/lib/trackerific/version.rb

@@ -0,0 +1,3 @@
+module Trackerific
+  VERSION = "0.7.0"
+end

data/lib/trackerific.rb

@@ -1,86 +1,43 @@
-require 'rails'
-require 'helpers/options_helper'
+require 'trackerific/version'
 require 'trackerific/configuration'
-require 'trackerific/service'
 require 'trackerific/error'
 require 'trackerific/details'
 require 'trackerific/event'
+require 'trackerific/services'
+require 'trackerific/services/base'
 
-# require all the Trackerific services
-services_path = File.join(File.dirname(__FILE__), "trackerific", "services", "**", "*.rb")
-Dir[File.expand_path(services_path)].each { |file| require file }
+# add tracking services here
+require 'trackerific/services/fedex'
+require 'trackerific/services/ups'
+require 'trackerific/services/usps'
 
-# Trackerific provides package tracking to Rails apps.
 module Trackerific
-  
   class << self
-    # Gets a list of all Trackerific services
-    # @return [Array, Symbol] the services
-    # @api private
-    def services
-      # a service is any Trackerific class that descends from Trackerific::Service
-      # [:UPS, :FedEx, :USPS, :MockService]
-      @services ||= Trackerific.constants.reject { |const|
-        const unless Trackerific.const_get(const).superclass == Trackerific::Service
-      }
+    # Used to access the Trackerific service credentials
+    # @api public
+    def configuration
+      Trackerific::Configuration.config
     end
-    
-    # Gets a Trackerific::Service class
-    # @param [Symbol] name the name of the service
-    # @return [Trackerific::Service] the service, or nil
-    # @api private
-    def service_get(name)
-      services.each do |service|
-        return Trackerific.const_get(service) if name == service.to_s.downcase.to_sym
-      end
-      return nil
+
+    # Use to configure Trackerific service credentials
+    # @example Configure FedEx credentials
+    #   Trackerific.configure do |config|
+    #     config.fedex account: 'account', meter: '123456789'
+    #   end
+    # @api public
+    def configure(&block)
+      Trackerific::Configuration.configure {|config| yield(config) }
     end
-  end
-  
-  # Checks a string for a valid package tracking service
-  # @param [String] package_id the package identifier
-  # @return [Trackerific::Base] the Trackerific class that can track the given
-  #   package id, or nil if none found.
-  # @example Find out which service provider will track a valid FedEx number
-  #   include Trackerific
-  #   tracking_service "183689015000001" # => Trackerific::FedEx
-  # @api public
-  def tracking_service(package_id)
-    # loop through all the services
-    Trackerific.services.each do |service|
-      # get the class associated with this service
-      cls = Trackerific.const_get(service)
-      # loop through all the packge id regular expressions
-      cls.package_id_matchers.each do |matcher|
-        # return this class if the regular expression matches
-        return cls if package_id =~ matcher
-      end unless cls.package_id_matchers.nil?
+
+    # Looks up which service(s) can track the given ID and tracks it.
+    # @param [String] id The package identifier
+    # @return [Array, Trackerific::Details] The tracking results
+    # @raise [Trackerific::Error] Raised when the server returns an error
+    # @api public
+    def track(id)
+      Trackerific::Services.find_by_package_id(id).map do |service|
+        service.new.track(id)
+      end
     end
-    # if we've made it this far, nothing matched
-    nil
-  end
-  
-  # Tracks a package by determining its service from the package id
-  # @param [String] package_id the package identifier
-  # @return [Trackerific::Details] the tracking results
-  # @raise [Trackerific::Error] raised when the server returns an error (invalid credentials, tracking package, etc.)
-  # @example Track a package
-  #   include Trackerific
-  #   # make sure to configure Trackerific before hand with the different services credentials
-  #   Trackerific.config do |config|
-  #     config.fedex :meter => '123456789', :account => '123456789'
-  #   end
-  #   details = track_package "183689015000001"
-  # @api public
-  def track_package(package_id)
-    # find the service that will be able to track this package
-    service = tracking_service package_id
-    raise Trackerific::Error, "Cannot find a service to track package id #{package_id}" if service.nil?
-    # get the name of the service
-    service_name = service.to_s.split('::')[1].downcase
-    # get the default configuration for the service
-    options = Trackerific.configuration.send service_name
-    # track the package
-    service.new(options).track_package package_id
   end
 end

data/spec/lib/trackerific/configuration_spec.rb

@@ -1,44 +1,13 @@
 require 'spec_helper'
 
-describe "Trackerific.configuration" do
-  include Trackerific
-  
-  subject { Trackerific.configuration }
-  it { should be_a Trackerific::Configuration }
-  
-  context "with valid options" do
-    it "should not raise any errors" do
-      lambda {
-        Trackerific.configure do |config|
-          config.usps :user_id => 'userid'
-        end
-      }.should_not raise_error
-    end
-    it "should save a valid option" do
-      Trackerific.configure do |config|
-        config.usps :user_id => 'userid'
-      end
-      Trackerific.configuration.usps[:user_id].should eq 'userid'
-    end
-  end
-  
-  context "with invalid options" do
-    it "should raise ArgumentError" do
-      lambda {
-        Trackerific.configure do |config|
-          config.usps :invalid => 'option'
-        end
-      }.should raise_error ArgumentError
-    end
-  end
-  
-  context "with invalid configuration group - not a Trackerific:Service" do
-    it "should raise NoMethodError" do
-      lambda {
-        Trackerific.configure do |config|
-          config.qwertyuiop :invalid => 'group'
-        end
-      }.should raise_error(NoMethodError)
+describe Trackerific::Configuration do
+  before do
+    Trackerific::Configuration.configure do |config|
+      config.hello = 'world'
     end
   end
+
+  subject { described_class.config }
+
+  its(:hello) { should eq 'world' }
 end