trackerific 0.3.2 → 0.3.3

data/doc/top-level-namespace.html

@@ -94,7 +94,7 @@
 </div>
     
     <div id="footer">
-  Generated on Mon Jun 13 16:20:06 2011 by 
+  Generated on Mon Jun 13 21:28:36 2011 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.7.1 (ruby-1.9.2).
 </div>

data/lib/trackerific.rb

@@ -1,71 +1,15 @@
-# Trackerific is a UPS, FedEx and USPS tracking provider.
+require 'rails'
+require 'trackerific/base'
+require 'trackerific/error'
+require 'trackerific/details'
+require 'trackerific/event'
+
+# 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 }
+
+# Trackerific provides package tracking to Rails apps.
 module Trackerific
-  require 'rails'
-  require 'trackerific_details'
-  require 'trackerific_event'
-  
-  # Raised if something other than tracking information is returned.
-  class Error < StandardError; end
-  
-  # Base class for Trackerific package tracking services.
-  class Base
-    # Creates a new instance of Trackerific::Base with required options
-    # @api private
-    def initialize(options = {})
-      required = required_options
-      # make sure all the required options exist
-      required.each do |k|
-        raise ArgumentError.new("Missing required parameter: #{k}") unless options.has_key?(k)
-      end
-      # make sure no invalid options exist
-      options.each do |k, v|
-        raise ArgumentError.new("Invalid parameter: #{k}") unless required.include?(k)
-      end
-      @options = options
-    end
-    
-    # Gets the tracking information for the package from the server
-    # @param [String] package_id the package identifier
-    # @return [Trackerific::Details] the tracking details
-    # @example Override this method in your custom tracking provider to implement tracking
-    #   module Trackerific
-    #     class MyTrackingProvider < Base
-    #       def track_package
-    #         Trackerific::Details.new(
-    #           "summary of tracking events",
-    #           [Trackerific::Event.new(Time.now, "summary", "location")]
-    #         )
-    #       end
-    #     end
-    #   end
-    # @api public
-    def track_package(package_id)
-      @package_id = package_id
-    end
-    
-    protected
-    
-    # An array of options that are required to create a new instance of this class
-    # @return [Array] the required options
-    # @example Override this method in your custom tracking provider to enforce some options
-    #   module Trackerific
-    #     class MyTrackingProvider < Base
-    #       def required_options
-    #         [:all, :these, :are, :required]
-    #       end
-    #     end
-    #   end
-    # @api private
-    def required_options
-      []
-    end
-    
-  end
-  
-  require 'usps'
-  require 'fedex'
-  require 'ups'
-  
   # 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
@@ -75,14 +19,33 @@ module Trackerific
   #   tracking_service "183689015000001" # => Trackerific::FedEx
   # @api public
   def tracking_service(package_id)
-    case package_id
-      when /^.Z/, /^[HK].{10}$/ then Trackerific::UPS
-      when /^96.{20}$/ then Trackerific::FedEx
-      else case package_id.length
-        when 13, 20, 22, 30 then Trackerific::USPS
-        when 12, 15, 19 then Trackerific::FedEx
-        else nil
+    # loop through each constant in Trackerific
+    Trackerific.constants.each do |const|
+      # get the constant's class
+      cls = Trackerific.const_get(const)
+      # check if it descends from Trackerific::Base
+      if cls.superclass == Trackerific::Base
+        # loop through each package id matcher
+        cls.package_id_matchers.each do |matcher|
+          # return the class if it matches
+          return cls if package_id =~ matcher
+        end
       end
     end
+    # if we've made it this far, nothing matched
+    nil
   end
+  
+  # TODO: 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
+  #   details = track_package("183689015000001")
+  # @api public
+#  def track_package(package_id)
+#    service = tracking_service(package_id)
+#    
+#  end
 end

data/lib/trackerific/base.rb

@@ -0,0 +1,70 @@
+module Trackerific
+  # Base class for Trackerific package tracking services.
+  class Base
+    # Creates a new instance of Trackerific::Base with required options
+    # @api private
+    def initialize(options = {})
+      required = self.class.required_options
+      # make sure all the required options exist
+      required.each do |k|
+        raise ArgumentError.new("Missing required parameter: #{k}") unless options.has_key?(k)
+      end
+      # make sure no invalid options exist
+      options.each do |k, v|
+        raise ArgumentError.new("Invalid parameter: #{k}") unless required.include?(k)
+      end
+      @options = options
+    end
+    
+    # Gets the tracking information for the package from the server
+    # @param [String] package_id the package identifier
+    # @return [Trackerific::Details] the tracking details
+    # @example Override this method in your custom tracking service to implement tracking
+    #   module Trackerific
+    #     class MyTrackingService < Base
+    #       def track_package
+    #         # your tracking code here
+    #         Trackerific::Details.new(
+    #           "summary of tracking events",
+    #           [Trackerific::Event.new(Time.now, "summary", "location")]
+    #         )
+    #       end
+    #     end
+    #   end
+    # @api semipublic
+    def track_package(package_id)
+      @package_id = package_id
+    end
+    
+    # An Array of Regexp that matches valid package identifiers for your service
+    # @example Override this method in your custom tracking service
+    #   module Trackerific
+    #     class MyTrackingService < Base
+    #       def self.package_id_matchers
+    #         [ /^.Z/, /^[HK].{10}$/ ]  # matchers for UPS package identifiers
+    #       end
+    #     end
+    #   end
+    # @return [Array, Regexp] an array of regular expressions
+    # @api semipublic
+    def self.package_id_matchers
+      nil
+    end
+    
+    # An array of options that are required to create a new instance of this class
+    # @return [Array] the required options
+    # @example Override this method in your custom tracking service to enforce some options
+    #   module Trackerific
+    #     class MyTrackingService < Base
+    #       def self.required_options
+    #         [:all, :these, :are, :required]
+    #       end
+    #     end
+    #   end
+    # @api semipublic
+    def self.required_options
+      []
+    end
+    
+  end
+end

data/lib/trackerific/error.rb

@@ -0,0 +1,4 @@
+module Trackerific
+  # Raised if something other than tracking information is returned.
+  class Error < StandardError; end
+end

data/lib/{fedex.rb → trackerific/services/fedex.rb}

@@ -45,16 +45,23 @@ module Trackerific
       )
     end
     
-    protected
+    # A regex that matches valid package identifiers for FedEx package ids
+    # @return [Regexp] the regular expression
+    # @api private
+    def self.package_id_matchers
+      [ /^[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
     #   and :meter
     # @api private
-    def required_options
+    def self.required_options
       [:account, :meter]
     end
     
+    protected
+    
     # Builds the XML request to send to FedEx
     # @return [String] a FDXTrack2Request XML
     # @api private

data/lib/{ups.rb → trackerific/services/ups.rb}

@@ -37,15 +37,21 @@ module Trackerific
       end
     end
     
-    protected
-    
+    # A regex that matches valid package identifiers for UPS package ids
+    # @return [Regexp] the regular expression
+    # @api private
+    def self.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.
+    # @return [Array] the required options for tracking a UPS package
     # @api private
-    def required_options
+    def self.required_options
       [:key, :user_id, :password]
     end
     
+    protected
+    
     # Parses the response from UPS
     # @return [Trackerific::Details]
     # @api private

data/lib/{usps.rb → trackerific/services/usps.rb}

@@ -56,15 +56,22 @@ module Trackerific
       )
     end
     
-    protected
+    # A regex that matches valid package identifiers for USPS package ids
+    # @return [Regexp] the regular expression
+    # @api private
+    def self.package_id_matchers
+      [ /^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.
+    # @return [Array] the required options for tracking a UPS package
     # @api private
-    def required_options
+    def self.required_options
       [:user_id]
     end
     
+    protected
+    
     # Builds an XML request to send to USPS
     # @return [String] the xml request
     # @api private

data/spec/lib/trackerific/base_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+class TestBaseClass < Trackerific::Base
+  def self.required_options
+    [:required, :also_required]
+  end
+end
+
+describe 'Trackerific::Base' do
+  
+  before(:all) do
+    @base = Trackerific::Base.new
+  end
+
+  context "with a new Trackerific::Base class that has required options" do
+    context "has all the required options" do
+      it "should be able to create a new instance" do
+        t = TestBaseClass.new(:required => true, :also_required => :yup)
+        t.should be_a TestBaseClass
+      end
+    end
+    context "is missing some required options" do
+      it "should raise an ArgumentError" do
+        lambda { TestBaseClass.new() }.should raise_error(ArgumentError)
+      end
+    end
+    context "has an invalid option" do
+      it "should raise an ArgumentError" do
+        lambda { TestBaseClass.new(:unknown => :argument ) }.should raise_error(ArgumentError)
+      end
+    end
+  end
+  
+end

data/spec/lib/trackerific/error_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+describe 'Trackerific::Error' do
+  # nothing to do here, yet
+end

data/spec/lib/{fedex_spec.rb → trackerific/services/fedex_spec.rb}

@@ -6,19 +6,27 @@ FEDEX_TRACK_URL = "https://gateway.fedex.com/GatewayDC"
 describe "Trackerific::FedEx" do
   include Fixtures
   
-  before(:all) do
-    @package_id = "183689015000001"
-    @fedex = Trackerific::FedEx.new :account  => "123456789", :meter => "123456789"
+  describe :required_options do
+    subject { Trackerific::FedEx.required_options }
+    it { should include(:account) }
+    it { should include(:meter) }
   end
   
-  describe "track_package" do
+  describe :package_id_matchers do
+    it "should be an Array of Regexp" do
+      Trackerific::FedEx.package_id_matchers.should each { |m| m.should be_a Regexp }
+    end
+  end
+  
+  describe :track_package do
+    before(:all) do
+      @package_id = "183689015000001"
+      @fedex = Trackerific::FedEx.new :account  => "123456789", :meter => "123456789"
+    end
+    
     context "with a successful response from the server" do
       before(:each) do
-        FakeWeb.register_uri(
-          :post,
-          FEDEX_TRACK_URL,
-          :body => load_fixture(:fedex_success_response)
-        )
+        FakeWeb.register_uri(:post, FEDEX_TRACK_URL, :body => load_fixture(:fedex_success_response))
         @tracking = @fedex.track_package(@package_id)
       end
       specify { @tracking.should be_a Trackerific::Details }
@@ -29,13 +37,10 @@ describe "Trackerific::FedEx" do
         @tracking.summary.should_not be_empty
       end
     end
+    
     context "with an error response from the server" do
       before(:all) do
-        FakeWeb.register_uri(
-          :post,
-          FEDEX_TRACK_URL,
-          :body => load_fixture(:fedex_error_response)
-        )
+        FakeWeb.register_uri(:post, FEDEX_TRACK_URL, :body => load_fixture(:fedex_error_response))
       end
       specify { lambda { @fedex.track_package("invalid package id") }.should raise_error(Trackerific::Error) }
     end

data/spec/lib/{ups_spec.rb → trackerific/services/ups_spec.rb}

@@ -6,19 +6,28 @@ UPS_TRACK_URL = 'https://wwwcie.ups.com/ups.app/xml/Track'
 describe "Trackerific::UPS" do
   include Fixtures
   
-  before(:all) do
-    @package_id = '1Z12345E0291980793'
-    @ups = Trackerific::UPS.new :key => 'testkey', :user_id => 'testuser', :password => 'secret'
+  describe :required_options do
+    subject { Trackerific::UPS.required_options }
+    it { should include(:key) }
+    it { should include(:user_id) }
+    it { should include(:password) }
   end
   
-  describe "track_package" do
+  describe :package_id_matchers do
+    it "should be an Array of Regexp" do
+      Trackerific::UPS.package_id_matchers.should each { |m| m.should be_a Regexp }
+    end
+  end
+  
+  describe :track_package do
+    before(:all) do
+      @package_id = '1Z12345E0291980793'
+      @ups = Trackerific::UPS.new :key => 'testkey', :user_id => 'testuser', :password => 'secret'
+    end
+    
     context "with a successful response from the server" do
       before(:all) do
-        FakeWeb.register_uri(
-          :post,
-          UPS_TRACK_URL,
-          :body => load_fixture(:ups_success_response)
-        )
+        FakeWeb.register_uri(:post, UPS_TRACK_URL, :body => load_fixture(:ups_success_response))
         @tracking = @ups.track_package(@package_id)
       end
       specify { @tracking.should be_a Trackerific::Details }
@@ -29,13 +38,10 @@ describe "Trackerific::UPS" do
         @tracking.summary.should_not be_empty
       end
     end
+    
     context "with an error response from the server" do
       before(:all) do
-        FakeWeb.register_uri(
-          :post,
-          UPS_TRACK_URL,
-          :body => load_fixture(:ups_error_response)
-        )
+        FakeWeb.register_uri(:post, UPS_TRACK_URL, :body => load_fixture(:ups_error_response))
       end
       specify { lambda { @ups.track_package("invalid package id") }.should raise_error(Trackerific::Error) }
     end