trackerific 0.3.5 → 0.4.0

data/lib/helpers/options_helper.rb

@@ -0,0 +1,20 @@
+# Helper for validating required options
+module OptionsHelper
+  # Validates a list of options against a list of required options
+  # @param [Array] options list of options to validate
+  # @param [Array] required list of required options
+  # @return true
+  # @raise [ArgumentError] if the options do not pass validation
+  # @api private
+  def validate_options(options, required)
+    # 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
+    true
+  end
+end

data/lib/trackerific.rb

@@ -1,5 +1,7 @@
 require 'rails'
-require 'trackerific/base'
+require 'helpers/options_helper'
+require 'trackerific/configuration'
+require 'trackerific/service'
 require 'trackerific/error'
 require 'trackerific/details'
 require 'trackerific/event'
@@ -10,6 +12,30 @@ Dir[File.expand_path(services_path)].each { |file| require file }
 
 # 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
+      Trackerific.constants.reject { |const|
+        const unless Trackerific.const_get(const).superclass == Trackerific::Service
+      }
+    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
+    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
@@ -19,33 +45,41 @@ module Trackerific
   #   tracking_service "183689015000001" # => Trackerific::FedEx
   # @api public
   def tracking_service(package_id)
-    # 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
+    # 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
     end
     # if we've made it this far, nothing matched
     nil
   end
   
-  # TODO: Tracks a package by determining its service from the package id
+  # 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")
+  #   # 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)
-#    service = tracking_service(package_id)
-#    
-#  end
+  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/lib/trackerific/configuration.rb

@@ -0,0 +1,49 @@
+module Trackerific
+  # Provides a dynamic configuration
+  class Configuration
+    include OptionsHelper
+    # Creates a new instance of Trackerific::Configuration
+    # @api private
+    def initialize
+      @options = {}
+    end
+    # Overriding the method_missing method allows dynamic methods
+    # @return [Hash]
+    # @api private
+    def method_missing(sym, *args, &block)
+      # Get a list of all the services (convert symbols to lower case)
+      services = Trackerific.services.map { |service| service.to_s.downcase.to_sym }
+      # Do not accept any configuration values for anything except services
+      raise NoMethodError unless services.include? sym
+      # Only accept Hashes
+      unless args.empty?
+        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
+        # Store the configuration options
+        @options[sym] = args[0]
+      end
+      # return the configuration options
+      @options[sym]
+    end
+  end
+  class << self
+    # Stores the configuration options for Trackerific
+    # @return [Trackerific::Configuration]
+    # @api private
+    def configuration
+      @configuration ||= Trackerific::Configuration.new
+    end
+    # Configures Trackerific
+    # @return [Trackerific::Configuration]
+    # @example Defining credentials
+    #   Trackerific.configure do |config|
+    #     config.fedex :meter => '123456789', :account => '123456789'
+    #   end
+    # @api public
+    def configure
+      yield configuration
+      configuration
+    end
+  end
+end

data/lib/trackerific/service.rb

@@ -0,0 +1,68 @@
+module Trackerific
+  # Base class for Trackerific services
+  class Service
+    include OptionsHelper
+    
+    # Creates a new instance of Trackerific::Service with required options
+    # @api private
+    def initialize(options = {})
+      validate_options options, self.class.required_options
+      @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 < Trackerific::Service
+    #       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
+    
+    class << self
+    
+      # 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 < Service
+      #       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 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 < Service
+      #       def self.required_options
+      #         [:all, :these, :are, :required]
+      #       end
+      #     end
+      #   end
+      # @api semipublic
+      def required_options
+        []
+      end
+      
+    end
+    
+  end
+end

data/lib/trackerific/services/fedex.rb

@@ -3,12 +3,29 @@ require 'httparty'
 module Trackerific
   
   # Provides package tracking support for FedEx
-  class FedEx < Base
+  class FedEx < Trackerific::Service
     # setup HTTParty
     include ::HTTParty
     format :xml
     base_uri "https://gateway.fedex.com"
     
+    class << self
+      # An Array of Regexp that matches valid FedEx package IDs
+      # @return [Array, Regexp] the regular expression
+      # @api private
+      def 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
+        [:account, :meter]
+      end
+    end
+    
     # Tracks a FedEx package
     # @param [String] package_id the package identifier
     # @return [Trackerific::Details] the tracking details
@@ -45,21 +62,6 @@ module Trackerific
       )
     end
     
-    # An Array of Regexp that matches valid FedEx package IDs
-    # @return [Array, 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 self.required_options
-      [:account, :meter]
-    end
-    
     protected
     
     # Builds the XML request to send to FedEx

data/lib/trackerific/services/ups.rb

@@ -4,7 +4,7 @@ module Trackerific
   require 'httparty'
   
   # Provides package tracking support for UPS.
-  class UPS < Base
+  class UPS < Trackerific::Service
     # setup HTTParty
     include ::HTTParty
     format :xml
@@ -14,6 +14,21 @@ module Trackerific
       when 'production' then 'https://www.ups.com/ups.app/xml'
     end : 'https://www.ups.com/ups.app/xml'
     
+    class << self
+      # An Array of Regexp that matches valid UPS package IDs
+      # @return [Array, Regexp] the regular expression
+      # @api private
+      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
+      # @api private
+      def required_options
+        [:key, :user_id, :password]
+      end
+    end
+    
     # Tracks a UPS package
     # @param [String] package_id the package identifier
     # @return [Trackerific::Details] the tracking details
@@ -37,19 +52,6 @@ module Trackerific
       end
     end
     
-    # An Array of Regexp that matches valid UPS package IDs
-    # @return [Array, 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
-    # @api private
-    def self.required_options
-      [:key, :user_id, :password]
-    end
-    
     protected
     
     # Parses the response from UPS

data/lib/trackerific/services/usps.rb

@@ -5,7 +5,7 @@ module Trackerific
   require 'httparty'
   
   # Provides package tracking support for USPS.
-  class USPS < Base
+  class USPS < Trackerific::Service
     # setup HTTParty
     include HTTParty
     format :xml
@@ -15,6 +15,22 @@ module Trackerific
       when 'production' then 'https://secure.shippingapis.com'
     end : 'https://secure.shippingapis.com'
     
+    class << self
+      # An Array of Regexp that matches valid USPS package IDs
+      # @return [Array, Regexp] the regular expression
+      # @api private
+      def 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
+      # @api private
+      def required_options
+        [:user_id]
+      end
+    end
+    
     # Tracks a USPS package
     # @param [String] package_id the package identifier
     # @return [Trackerific::Details] the tracking details
@@ -56,20 +72,6 @@ module Trackerific
       )
     end
     
-    # An Array of Regexp that matches valid USPS package IDs
-    # @return [Array, 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
-    # @api private
-    def self.required_options
-      [:user_id]
-    end
-    
     protected
     
     # Builds an XML request to send to USPS

data/spec/lib/trackerific/configuration_spec.rb

@@ -0,0 +1,9 @@
+require 'spec_helper'
+
+describe "Trackerific.configuration" do
+  include Trackerific
+  
+  subject { Trackerific.configuration }
+  it { should be_a Trackerific::Configuration }
+  
+end

data/spec/lib/trackerific/details_spec.rb

@@ -1,19 +1,22 @@
 require 'spec_helper'
 
 describe Trackerific::Details do
-  before(:all) do
-    @details = Trackerific::Details.new(String.new, String.new, Array.new)
-  end
+
+  before { @details = Trackerific::Details.new(String.new, String.new, Array.new) }
   
-  describe "events" do
-    specify { @details.events.should be_a Array }
+  describe :events do
+    subject { @details.events }
+    it { should be_a Array }
   end
   
-  describe "package_id" do
-    specify { @details.package_id.should be_a String }
+  describe :package_id do
+    subject { @details.package_id }
+    it { should be_a String }
   end
   
-  describe "summary" do
-    specify { @details.summary.should be_a String }
+  describe :summary do
+    subject { @details.summary }
+    it { should be_a String }
   end
+  
 end

data/spec/lib/trackerific/error_spec.rb

@@ -1,5 +1,9 @@
 require 'spec_helper'
 
-describe 'Trackerific::Error' do
-  # nothing to do here, yet
+describe Trackerific::Error do
+  
+  before { @error = Trackerific::Error.new }
+  subject { @error }
+  specify { should be_a StandardError }
+  
 end