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

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

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

== Extending

Here is a basic outline of a custom Trackerific service.

lib/trackerific/services/my_tracking_service.rb:
  module Trackerific
    class MyTrackingService < Trackerific::Base
      def self.required_options
        # any options your service requires. these are usually user credentials
        [ :some, :options ]
      end
      def self.package_id_matchers
        # write some custom regex matchers for your tracking package IDs
        [ /^[0-9]{15}$/ ] # fedex package matcher
      end
      def track_package(package_id)
        # implement your tracking code here
        Trackerific::Details.new(
          "summary",
          [
            Trackerific::Event.new(Time.now, "description", "location"),
            Trackerific::Event.new(Time.now, "description", "location")
          ]
        )
      end
    end
  end

spec/lib/trackerific/services/my_tracking_service_spec.rb:
  describe "Trackerific::MyTrackingService" do
    describe :required_options do
      subject { Trackerific::MyTrackingService.required_options }
      it { should include(:some) }
      it { should include(:options) }
    end
    describe :package_id_matchers do
      it "should be an Array of Regexp" do
        Trackerific::MyTrackingService.package_id_matchers.should each { |m| m.should be_a Regexp }
      end
    end
    describe :track_package do
      pending "your track_package specs"
    end
  end

Please make sure to include comments, documentation, and specs for your service.
Trackerific uses {RSpec}[https://github.com/dchelimsky/rspec] for tests,
{simplecov}[https://github.com/colszowka/simplecov] for code coverage,
and {Yardoc}[http://yardoc.org/] for documentation. You can also take advantage
of {yardstick}[https://github.com/dkubb/yardstick] to help verify the coverage
of the comments of your code. You can use the rake task:
  rake yardstick_measure
which will generate a measurement/report.txt file.

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