== Installation

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

=== Configuration

You will need to configure your credentials for each service:

  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

  details = Trackerific.track("package id")

=== Finding a Tracking Service Provider

If you do not know the tracking service provider of a package id you can use
Trackerific::Services.find_by_tracking_id:

  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:
  details = Trackerific::Services::FedEx.track('183689015000001')

  # Track a USPS package:
  details = Trackerific::Services::USPS.track('EJ958083578US')

  # Track a UPS package:
  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

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::Services::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
    details = Trackerific.track('EJ958083578US')
    # handle details here
  rescue Trackerific::Error => e
    puts e.message
  end

=== Testing

Trackerific provides a mocked service you can use in your unit tests of your
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::Error exception

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