File: README — Documentation by YARD 0.7.1

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

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 for tests, simplecov for code coverage, and Yardoc for documentation. You can also take advantage of 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.

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.