= Trackerific {<img src="https://badge.fury.io/rb/trackerific.png" alt="Gem Version" />}[http://badge.fury.io/rb/trackerific] {<img src="https://travis-ci.org/travishaynes/trackerific.png" />}[https://travis-ci.org/travishaynes/trackerific] {<img src="https://coveralls.io/repos/travishaynes/trackerific/badge.png" alt="Coverage Status" />}[https://coveralls.io/r/travishaynes/trackerific]

Package tracking in a gem. Currently supported carriers are:

* FedEx
* UPS
* USPS

== Prerequisites

You will need to sign up to each carrier you wish to utilize. They each have
their own requirements and license agreements, so it's up to you to make sure
you follow their terms of agreement. For example, at the time this was written
UPS requires that you include their logo on your website when you use their
API.

You'll also need the proper credentials from each carrier, which requires
signing up through their individual websites, and is not always free, depending
on which portion of their API you plan on using. Trackerific focuses primarily
on the tracking APIs, so that's all you'll need to use this gem, unless you
plan on implementing additional features.

== Installation

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

=== Configuration

You will need to configure the credentials for each service you're utilizing.
Services without credentials will not be accessed by the gem.

  Trackerific.configure do |config|
    config.fedex  = { account: 'account', meter: '123456789' }
    config.ups    = { key: 'key', user_id: 'userid', password: 'secret' }
    config.usps   = { user_id: 'userid' }
  end

=== 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("123456789012")
  Trackerific::Services.find_by_tracking_id("1Z12345E0291980793")
  Trackerific::Services.find_by_tracking_id("EJ958083578US")

Each of the above examples will return an Array of
Trackerific::Service::Base subclasses that are capable of tracking the given
package ID.

=== Tracking a Package with a Specific Service

Use this method if you need to specify exactly which service to track a package.

  details = Trackerific::Services::FedEx.track('123456789012')

Using #track will automatically read the credentials from Trackerific.config.
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 - Summary of the tracking events
details.events - Array of Trackerific::Events

=== Tracking Events

Tracking::Details has an events Array with the following properties:

event.date - The date the package was shipped.
event.date - The date/time of the event.
event.description - Description of an event.
event.location - The location of the package during that event.

Note that events are in last-in-first-out order, so the last event will always
be the first event the carrier supplied.

=== 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'
  # Get a populated Trackerific::Details
  details = Trackerific.track("XXXXXXXXXX")
  # Throw a Trackerific::Error exception
  details = Trackerific.track("XXXxxxxxxx")

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