== Installation

To use this gem, add this line to your Gemfile
  gem 'trackerific'
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.

  # 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.

=== Tracking with Automatic Service Discovery

Once you configured the services, tracking a package is as easy as

  include Trackerific
  details = track_package "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.

  include Trackerific
  tracking_service "183689015000001"    # => Trackerific::FedEx
  tracking_service "1Z12345E0291980793" # => Trackerific::UPS
  tracking_service "EJ958083578US"      # => Trackerific::USPS
  tracking_service "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')
  
  # Track a USPS package:
  usps = Trackerific::USPS.new :user_id => '123USERID4567'
  details = usps.track_package('EJ958083578US')
  
  # Track a UPS package:
  ups = Trackerific::UPS.new :user_id => 'userid', :key => 'kQdEJwuHBjtQ7g2', :password => 'secret'
  details = ups.track_package('1Z12345E0291980793')

=== Tracking Details

The tracking information is returned in a Trackerific::Details instance.

  details.summary # => a summary of the tracking events
  details.events  # => an Array of Trackerific::Events

You can easily print out the tracking events just by doing:

  puts details.events         # for all the events
  puts details.events.first   # for just one event

Or, if you need specific information about an event:

  details.events.last.date         # => the date the package was shipped
  details.events.first.date        # => the last date the package was updated
  details.events.first.description # => a description of an event
  details.events.first.location    # => the location of the package during that event

location will not work for USPS packages, because USPS does not provide that
information seperately from the description. So for USPS packages, the location
will always be at the end of the description.

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,
you enter the wrong number, or the tracking provider has yet to have added the
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')
  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

Here is a spec for writing a custom trackerific service:

  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
      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
      context "with an error response from the server" do
        specify { lambda { @service.track_package(@invalid_package_id) }.should raise_error(Trackerific::Error) }
      end
    end
    describe :required_options do
      subject { Trackerific::CustomService.required_options }
      it { should include(:required) }
    end
    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 :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

=== Testing with Trackerific

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.

  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

Copyright (c) 2011 Travis Haynes. See LICENSE.txt for
further details.