README.rdoc in trackerific-0.5.5 vs README.rdoc in trackerific-0.6.0

@@ -16,14 +16,24 @@
 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'
+    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
 
@@ -83,10 +93,18 @@
 
 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::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
@@ -96,62 +114,62 @@
     usps.track_package('EJ958083578US')
   rescue Trackerific::Error => e
     puts e.message
   end
 
-== Extending
+or for a Rails application:
 
-Here is a basic outline of a custom Trackerific service.
+  # in app/controllers/application_controller.rb
+  rescue_from Trackerific::Error do |exception|
+    redirect_to root_url, :alert => exception.message
+  end
 
-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 ]
+== Writing a Custom Service
+
+Here is a spec for writing a custom trackerific service:
+
+  describe Trackerific::CustomService do
+    specify("it should descend from Trackerific::Service") {
+      Trackerific::CustomService.superclass.should be Trackerific::Service
+    }
+    describe :track_package do
+      before do
+        @valid_package_id = 'valid package id'
+        @invalid_package_id = 'invalid package id'
+        @service = Trackerific::CustomService.new :required => 'option'
       end
-      def self.package_id_matchers
-        # write some custom regex matchers for your tracking package IDs
-        [ /^[0-9]{15}$/ ] # fedex package matcher
+      context "with a successful response from the server" do
+        before(:each) do
+          @tracking = @service.track_package(@valid_package_id)
+        end
+        subject { @tracking }
+        it("should return a Trackerific::Details") { should be_a Trackerific::Details }
+        describe :summary do
+          subject { @tracking.summary }
+          it { should_not be_empty }
+        end
       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")
-          ]
-        )
+      context "with an error response from the server" do
+        specify { lambda { @service.track_package(@invalid_package_id) }.should raise_error(Trackerific::Error) }
       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) }
+      subject { Trackerific::CustomService.required_options }
+      it { should include(:required) }
     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 }
+    describe :valid_options do
+      it "should include required_options" do
+        valid = Trackerific::CustomService.valid_options
+        Trackerific::CustomService.required_options.each do |opt|
+          valid.should include opt
+        end
       end
     end
-    describe :track_package do
-      pending "your track_package specs"
+    describe :package_id_matchers do
+      subject { Trackerific::CustomService.package_id_matchers }
+      it("should be an Array of Regexp") { should each { |m| m.should be_a Regexp } }
     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