== Installation:

To use this gem, add this line to your Gemfile
  gem 'trackerific'
and then run
  bundle install

== Usage:

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

=== Finding a Tracking Service Provider

If you do not know the tracking service provider of a package id, you can use
the tracking_service helper method to get a Trackerific class that most likely
will be able to track the given package id.

  include Trackerific
  tracking_service "183689015000001"    # => Trackerific::FedEx
  tracking_service "1Z12345E0291980793" # => Trackerific::UPS
  tracking_service "EJ958083578US"      # => Trackerific::USPS
  tracking_service "unknown package id" # => nil

=== 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

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