trackerific 0.6.2 → 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8805756f860d3296a7f8c74ccc73fa761306f5eb
+  data.tar.gz: 6983a95593bd7d48fcc090e6e6cf586829549647
+SHA512:
+  metadata.gz: aa16b48e0a34e396275a02d77109dc8d582ff2c219a7de922dd2d67c4dfe6541abca0892741d2a631976b53867c8ecc6acff9abb18199bc3155c2e79e4a6013b
+  data.tar.gz: 935b59bd04fd1286160f3fc823a4c3ebdd79819e42c820381cbcaa31f2b990c554f42bc658bbe400e8104ca645b07f87ec90a6cc5c5472ca7216af5bdbc424c3

data/.gitignore

@@ -0,0 +1,8 @@
+.bundle
+pkg
+log
+.yardoc
+measurement
+coverage
+doc
+.ruby-gemset

data/.rspec

@@ -1,2 +1 @@
---colour
---format d
+--color

data/Gemfile

@@ -1,23 +1,4 @@
-source "http://rubygems.org"
+source 'https://rubygems.org'
 
-gem "rails", ">= 3.0.0"
-
-gem "httparty", ">= 0.7.7"
-gem "builder", ">= 2.1.2"
-
-group :development do
-  gem "bundler", ">= 1.0.13"
-  gem "jeweler", ">= 1.5.2"
-  gem 'yardstick', ">= 0.4.0"
-end
-
-group :development, :test do
-  gem "rspec-rails", ">= 2.6.1"
-  gem "rspec_multi_matchers", ">= 1.1.0"
-  gem "ruby-debug19", ">= 0.11.6", :require => "ruby-debug"
-end
-
-group :test do
-  gem "fakeweb", ">= 1.3.0"
-  gem 'simplecov', '>= 0.4.0', :require => false
-end
+# Specify your gem's dependencies in trackerific.gemspec
+gemspec

data/Gemfile.lock

@@ -1,77 +1,32 @@
+PATH
+  remote: .
+  specs:
+    trackerific (0.7.0)
+      activesupport
+      builder (~> 3.2.2)
+      httparty (~> 0.12.0)
+
 GEM
-  remote: http://rubygems.org/
+  remote: https://rubygems.org/
   specs:
-    abstract (1.0.0)
-    actionmailer (3.0.8)
-      actionpack (= 3.0.8)
-      mail (~> 2.2.19)
-    actionpack (3.0.8)
-      activemodel (= 3.0.8)
-      activesupport (= 3.0.8)
-      builder (~> 2.1.2)
-      erubis (~> 2.6.6)
-      i18n (~> 0.5.0)
-      rack (~> 1.2.1)
-      rack-mount (~> 0.6.14)
-      rack-test (~> 0.5.7)
-      tzinfo (~> 0.3.23)
-    activemodel (3.0.8)
-      activesupport (= 3.0.8)
-      builder (~> 2.1.2)
-      i18n (~> 0.5.0)
-    activerecord (3.0.8)
-      activemodel (= 3.0.8)
-      activesupport (= 3.0.8)
-      arel (~> 2.0.10)
-      tzinfo (~> 0.3.23)
-    activeresource (3.0.8)
-      activemodel (= 3.0.8)
-      activesupport (= 3.0.8)
-    activesupport (3.0.8)
-    archive-tar-minitar (0.5.2)
-    arel (2.0.10)
-    builder (2.1.2)
-    columnize (0.3.3)
-    crack (0.1.8)
+    activesupport (4.0.0)
+      i18n (~> 0.6, >= 0.6.4)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    atomic (1.1.14)
+    builder (3.2.2)
     diff-lcs (1.1.2)
-    erubis (2.6.6)
-      abstract (>= 1.0.0)
     fakeweb (1.3.0)
-    git (1.2.5)
-    httparty (0.7.8)
-      crack (= 0.1.8)
-    i18n (0.5.0)
-    jeweler (1.6.2)
-      bundler (~> 1.0)
-      git (>= 1.2.5)
-      rake
-    linecache19 (0.5.12)
-      ruby_core_source (>= 0.1.4)
-    mail (2.2.19)
-      activesupport (>= 2.3.6)
-      i18n (>= 0.4.0)
-      mime-types (~> 1.16)
-      treetop (~> 1.4.8)
-    mime-types (1.16)
-    polyglot (0.3.1)
-    rack (1.2.3)
-    rack-mount (0.6.14)
-      rack (>= 1.0.0)
-    rack-test (0.5.7)
-      rack (>= 1.0)
-    rails (3.0.8)
-      actionmailer (= 3.0.8)
-      actionpack (= 3.0.8)
-      activerecord (= 3.0.8)
-      activeresource (= 3.0.8)
-      activesupport (= 3.0.8)
-      bundler (~> 1.0)
-      railties (= 3.0.8)
-    railties (3.0.8)
-      actionpack (= 3.0.8)
-      activesupport (= 3.0.8)
-      rake (>= 0.8.7)
-      thor (~> 0.14.4)
+    httparty (0.12.0)
+      json (~> 1.8)
+      multi_xml (>= 0.5.2)
+    i18n (0.6.5)
+    json (1.8.0)
+    minitest (4.7.5)
+    multi_json (1.8.1)
+    multi_xml (0.5.5)
     rake (0.9.2)
     rspec (2.6.0)
       rspec-core (~> 2.6.0)
@@ -81,45 +36,16 @@ GEM
     rspec-expectations (2.6.0)
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.6.0)
-    rspec-rails (2.6.1)
-      actionpack (~> 3.0)
-      activesupport (~> 3.0)
-      railties (~> 3.0)
-      rspec (~> 2.6.0)
-    rspec_multi_matchers (1.1.0)
-    ruby-debug-base19 (0.11.25)
-      columnize (>= 0.3.1)
-      linecache19 (>= 0.5.11)
-      ruby_core_source (>= 0.1.4)
-    ruby-debug19 (0.11.6)
-      columnize (>= 0.3.1)
-      linecache19 (>= 0.5.11)
-      ruby-debug-base19 (>= 0.11.19)
-    ruby_core_source (0.1.5)
-      archive-tar-minitar (>= 0.5.2)
-    simplecov (0.4.2)
-      simplecov-html (~> 0.4.4)
-    simplecov-html (0.4.5)
-    thor (0.14.6)
-    treetop (1.4.9)
-      polyglot (>= 0.3.1)
-    tzinfo (0.3.28)
-    yard (0.7.1)
-    yardstick (0.4.0)
-      yard (~> 0.7.0)
+    thread_safe (0.1.3)
+      atomic
+    tzinfo (0.3.38)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  builder (>= 2.1.2)
-  bundler (>= 1.0.13)
-  fakeweb (>= 1.3.0)
-  httparty (>= 0.7.7)
-  jeweler (>= 1.5.2)
-  rails (>= 3.0.0)
-  rspec-rails (>= 2.6.1)
-  rspec_multi_matchers (>= 1.1.0)
-  ruby-debug19 (>= 0.11.6)
-  simplecov (>= 0.4.0)
-  yardstick (>= 0.4.0)
+  bundler (>= 1.3.5)
+  fakeweb (~> 1.3.0)
+  rake
+  rspec (~> 2.6.0)
+  trackerific!

data/README.rdoc

@@ -5,30 +5,22 @@ To use this gem, add this line to your Gemfile
 and then run
   bundle install
 
-== Usage
-
-If you would like to see a functional example of this gem in action, check out the
-sample Rails app here: {package-tracker}[https://github.com/travishaynes/package-tracker]
-
 === Configuration
 
-To take advantage of Trackerific's automatic service discovery, you will need to
-configure your credentials for each service.
+You will need to 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',
                   :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.
@@ -37,36 +29,36 @@ it, this feature will provide the location for USPS package events.
 
 Once you configured the services, tracking a package is as easy as
 
-  include Trackerific
-  details = track_package "package id"
+  details = Trackerific.track("package id")
 
 === Finding a Tracking Service Provider
 
-If you do not know the tracking service provider of a package id, or you used
-track_package, and you need to know which service was used to track it, you can
-use the tracking_service helper method.
+If you do not know the tracking service provider of a package id you can use
+Trackerific::Services.find_by_tracking_id:
 
-  include Trackerific
-  tracking_service "183689015000001"    # => Trackerific::FedEx
-  tracking_service "1Z12345E0291980793" # => Trackerific::UPS
-  tracking_service "EJ958083578US"      # => Trackerific::USPS
-  tracking_service "unknown package id" # => nil
+  Trackerific::Services.find_by_tracking_id("183689015000001")    # => Trackerific::Services::FedEx
+  Trackerific::Services.find_by_tracking_id("1Z12345E0291980793") # => Trackerific::Services::UPS
+  Trackerific::Services.find_by_tracking_id("EJ958083578US")      # => Trackerific::Services::USPS
+  Trackerific::Services.find_by_tracking_id("unknown package id") # => nil
 
 === Tracking a Package with a Specific Service
 
 Use this method if you need to specify exactly which service to track a package.
 
   # Track a FedEx package:
-  fedex = Trackerific::FedEx.new :account => '123456789', :meter => '123456789'
-  details = fedex.track_package('183689015000001')
-  
+  details = Trackerific::Services::FedEx.track('183689015000001')
+
   # Track a USPS package:
-  usps = Trackerific::USPS.new :user_id => '123USERID4567'
-  details = usps.track_package('EJ958083578US')
-  
+  details = Trackerific::Services::USPS.track('EJ958083578US')
+
   # Track a UPS package:
-  ups = Trackerific::UPS.new :user_id => 'userid', :key => 'kQdEJwuHBjtQ7g2', :password => 'secret'
-  details = ups.track_package('1Z12345E0291980793')
+  details = Trackerific::Services::UPS.track('1Z12345E0291980793')
+
+Using #track will automatically read the credentials from
+`Trackerific.configuration`. If you need to assign them manually, use #new:
+
+  fedex = Trackerific::Services::FedEx.new account: "account", meter: "123456789"
+  details = fedex.track('183689015000001')
 
 === Tracking Details
 
@@ -100,7 +92,7 @@ recent events will always be at the top of the list.
 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 = Trackerific::Services::USPS.new :user_id => 'userid'
   usps.city_state_lookup "90210" # => { :city => 'BEVERLY HILLS', :state => 'CA', :zip => '90210' }
 
 === Exception handling
@@ -111,43 +103,25 @@ tracking number to their system, a Trackerific::Error will be raised. Here's an
 example on how to handle Trackerific::Errors:
 
   begin
-    usps.track_package('EJ958083578US')
+    details = Trackerific.track('EJ958083578US')
+    # handle details here
   rescue Trackerific::Error => e
     puts e.message
   end
 
-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
-
-See the examples folder for an example of a custom service.
-
-=== Testing with Trackerific
+=== Testing
 
 Trackerific provides a mocked service you can use in your unit tests of your
-application. The mocked service will be available in development and test
-environments only, and disabled in production.
+application. You must require the service manually.
 
+  require 'trackerific/services/mock_service'
   details = track_package("XXXXXXXXXX") # => returns a populated Trackerific::Details
-  details = track_package("XXXxxxxxxx") # => throws a Trackerific::Errror exception
-
-== Contributing to trackerific
-
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
-* Fork the project
-* Start a feature/bugfix branch
-* Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-
-== Copyright
+  details = track_package("XXXxxxxxxx") # => throws a Trackerific::Error exception
 
-Copyright (c) 2011 Travis Haynes. See LICENSE.txt for
-further details.
+== Contributing
 
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -1,40 +1,14 @@
-require 'rubygems'
-require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
-
-require 'jeweler'
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "trackerific"
-  gem.homepage = "http://github.com/travishaynes/trackerific"
-  gem.license = "MIT"
-  gem.summary = %Q{Trackerific provides 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"
-end
-Jeweler::RubygemsDotOrgTasks.new
-
-# measure coverage
-
-require 'yardstick/rake/measurement'
-
-Yardstick::Rake::Measurement.new(:yardstick_measure) do |measurement|
-  measurement.output = 'measurement/report.txt'
-end
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
-# verify coverage
+RSpec::Core::RakeTask.new(:spec)
 
-require 'yardstick/rake/verify'
+task :default => :spec
 
-Yardstick::Rake::Verify.new do |verify|
-  verify.threshold = 100
+desc 'Starts an IRB console with Trackerific loaded'
+task :console do
+  require 'irb'
+  require 'trackerific'
+  ARGV.clear
+  IRB.start
 end

data/lib/trackerific/configuration.rb

@@ -1,50 +1,7 @@
+require 'active_support'
+
 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
-      unless args.empty?
-        # Only accept Hashes
-        raise ArgumentError unless args[0].class == Hash
-        # Validate configuration values against the required parameters for that service
-        service = Trackerific.service_get(sym)
-        validate_options args[0], service.required_parameters, service.valid_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
+    include ActiveSupport::Configurable
   end
 end

data/lib/trackerific/details.rb

@@ -1,75 +1,6 @@
 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 [Hash] details The details for this package
-    # @api private
-    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
-    
-    # The package identifier
-    # @example Get the id of a tracked package
-    #   details.package_id # => the package identifier
-    # @return [String] the package identifier
-    # @api public
-    def package_id
-      @package_id
-    end
-    
-    # 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
-    # @api public
-    def summary
-      @summary
-    end
-    
-    # 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
-    #   details.events.last.date # => a DateTime value
-    # @example A bulleted HTML list of the events (most current on top) in haml
-    #   %ul
-    #     - details.events.each do |event|
-    #       %li= event
-    # @return [Array, Trackerific::Event] the tracking events
-    # @api public
-    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
+  # a summary, and the events, etc.
+  class Details < Struct.new(:package_id, :summary, :events, :weight, :via)
   end
 end

data/lib/trackerific/event.rb

@@ -1,60 +1,16 @@
 module Trackerific
   # Provides details for a tracking event
-  class Event
-    include OptionsHelper
-    
-    # Provides a new instance of Event
-    # @param [Hash] details The details of the event
-    # @api private
-    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
-    # @example Get the date of an event
-    #   date = details.events.first.date
-    # @return [DateTime]
-    # @api public
-    def date
-      @date
-    end
-    
-    # The event's description
-    # @example Get the description of an event
-    #   description = details.events.first.description
-    # @return [String]
-    # @api public
-    def description
-      @description
-    end
-    
-    # Where the event took place (usually in City State Zip format)
-    # @example Get the location of an event
-    #   location = details.events.first.location
-    # @return [String]
-    # @api public
-    def location
-      @location
-    end
-    
+  class Event < Struct.new(:date, :description, :location)
     # Converts the event into a string
     # @example Get a human-readable string from an event
     #   event = details.event.to_s
-    # @example A bulleted list of events in haml
-    #   %ul
-    #     - details.events.each do |event|
-    #     %li= event
     # @return [String] converts the event into a string
     # @api public
     def to_s
-      dte = self.date.strftime('%b %d %I:%M %P')
-      des = self.description
-      loc = self.location
-      "#{dte} #{des} #{loc}"
+      [ date.strftime('%b %d %I:%M %P'),
+        description,
+        location
+      ].join(" ")
     end
   end
 end

data/lib/trackerific/services/base.rb

@@ -0,0 +1,45 @@
+module Trackerific
+  module Services
+    class Base
+      class << self
+        attr_accessor :name
+
+        # Registers the service with Trackerific
+        # @api semipublic
+        def register(name)
+          self.name = name.to_sym
+          Trackerific::Services[self.name] = self
+        end
+
+        def track(id)
+          options = Trackerific.configuration[self.name] || {}
+          new(options).track(id)
+        end
+
+        # Checks if the given package ID can be tracked by this service
+        # @param [String] id The package ID
+        # @return [Boolean] true when this service can track the given ID
+        def can_track?(id)
+          package_id_matchers.each {|m| return true if id =~ m }
+          false
+        end
+
+        # An Array of Regexp that matches valid package ids for the service
+        # @api semipublic
+        def package_id_matchers
+          raise NotImplementedError,
+            "You must implement this method in your service", caller
+        end
+      end
+    end
+
+    # Gets the tracking information for the package from the server
+    # @param [String] id The package identifier
+    # @return [Trackerific::Details] The tracking details
+    # @api semipublic
+    def track(id)
+      raise NotImplementedError,
+        "You must implement this method in your service", caller
+    end
+  end
+end