package_tracker 0.0.2

data/.autotest

@@ -0,0 +1,16 @@
+# ./.autotest
+Autotest.add_hook(:initialize) {|at|
+  at.add_exception %r{^\.git}  # ignore Version Control System
+  at.add_exception %r{^./tmp}  # ignore temp files, lest autotest will run again, and again...
+  
+  at.clear_mappings         # take out the default (test/test*rb)
+  
+  at.add_mapping(%r{^lib/.*\.rb$}) {|f, _|
+    Dir['spec/**/*_spec.rb']
+  }
+  at.add_mapping(%r{^spec/.*\.rb$}) {|f, _|
+    Dir['spec/**/*_spec.rb']
+  }
+  
+  nil
+}

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rvmrc

@@ -0,0 +1 @@
+rvm 1.9.2

data/Gemfile

@@ -0,0 +1,12 @@
+source 'http://rubygems.org'
+
+gem 'nokogiri'
+gem 'facets'
+
+group :development do
+  gem 'bundler', '~> 1.0.0'
+  gem 'jeweler', '~> 1.6.0'
+  gem 'rcov', '>= 0'
+  gem 'rspec', '~> 2.6.0'
+  gem 'webmock'
+end

data/Gemfile.lock

@@ -0,0 +1,38 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.6)
+    crack (0.1.8)
+    diff-lcs (1.1.2)
+    facets (2.9.1)
+    git (1.2.5)
+    jeweler (1.6.0)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    nokogiri (1.4.4)
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.0)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    webmock (1.6.2)
+      addressable (>= 2.2.2)
+      crack (>= 0.1.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  facets
+  jeweler (~> 1.6.0)
+  nokogiri
+  rcov
+  rspec (~> 2.6.0)
+  webmock

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Michael Taras
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,53 @@
+= PackageTracker
+
+PackageTracker is a ruby gem for fetching the status of a packages(UPS, FedEx, etc...) with a simple API.  Currently only UPS and FedEx are supported.  More docs and carrier support to come soon...
+
+
+== Installation
+
+To install:
+
+    gem install package_tracker
+
+
+== Usage
+
+    @client = PackageTracker::Client.new(Yaml.load_file("credentials.yaml"))
+    
+    fedex_response = @client.track("999999999999")
+    # => PackageTracker::Response
+    
+    fedex_response.delivered? 
+    # => true
+    
+    fedex_response.statuses 
+    # => [{:message => "DELIVERED", :location => "San Francsico, CA, USA", :time => 2011-04-22 00:00:00 -0700}, ...]
+    
+    ups_response = @client.track("1Z9999999999999999")
+    # and so on...
+
+== Configuration
+
+PackageTracker::Client::new takes a hash of credentials with the following parameters:
+
+    {
+      :ups => {
+        :key => "key"
+        :user_id => "user id"
+        :password => "password"
+      },
+      :fedex => {
+        :password => "password",
+        :key => "key",
+        :account => "account",
+        :meter => "meter number"
+      }
+    }
+    
+It's usually easiest to put those credentials in a YAML file and load them in.  That makes it easy to keep your sensitive password info out of git as well.
+
+If you just want to hit the carriers' test servers, you can set your client to test mode:
+    @client = PackageTracker::Client.new(Yaml.load_file("credentials.yaml"))
+    
+    @client.test_mode!
+    # => all requests will now to to the carriers' test servers

data/Rakefile

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "package_tracker"
+  gem.homepage = "http://github.com/michaeltaras/package_tracker"
+  gem.license = "MIT"
+  gem.summary = %Q{PackageTracker is a ruby gem for fetching the status of a packages(UPS, FedEx, etc...) with a simple API.}
+  gem.description = %Q{PackageTracker is a ruby gem for fetching the status of a packages(UPS, FedEx, etc...) with a simple API.}
+  gem.email = "michaeltaras@gmail.com"
+  gem.authors = ["Michael Taras"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "package_tracker #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.2

data/lib/package_tracker/carrier.rb

@@ -0,0 +1,9 @@
+module PackageTracker
+  module Carrier    
+    def validate_credentials!(credentials)
+      required_credentials.each do |key| 
+        raise MissingCredentialsError, "You must provide a #{key} in the options" unless credentials && credentials[key]
+      end
+    end
+  end
+end

data/lib/package_tracker/carriers/fedex.rb

@@ -0,0 +1,106 @@
+module PackageTracker
+  module Carriers
+    module FedEx
+      extend Carrier
+      extend self
+      
+      TEST_URL = 'gatewaybeta.fedex.com'
+      LIVE_URL = 'gateway.fedex.com'
+    
+      PATH = "/xml"
+      PORT = "443"
+        
+      def track(tracking_number, options)
+        validate_credentials!(options[:credentials])
+        repsonse = Request.post(
+          request_url(options[:testing]), 
+          PATH, 
+          request_data(tracking_number, options[:credentials]), 
+          :https => true,
+          :port => PORT
+        )
+        parse_response(tracking_number, repsonse)
+      end
+      
+      def match(tracking_number)
+        tracking_number =~ /^\w{9}$/ || tracking_number =~ /^\d{12,15}$/ || tracking_number =~ /^96\d{20}$/
+      end
+      
+      def delivered_status
+        "Delivered"
+      end
+
+      private
+    
+      def required_credentials
+        [:key, :password, :account, :meter]
+      end
+    
+      def request_url(testing)
+        testing ? TEST_URL : LIVE_URL
+      end
+    
+      def request_data(tracking_number, credentials)
+        "<?xml version='1.0'?>
+         <TrackRequest xmlns='http://fedex.com/ws/track/v3'>
+           <WebAuthenticationDetail>
+             <UserCredential>
+               <Key>#{credentials[:key]}</Key>
+               <Password>#{credentials[:password]}</Password>
+             </UserCredential>
+           </WebAuthenticationDetail>
+           <ClientDetail>
+             <AccountNumber>#{credentials[:account]}</AccountNumber>
+             <MeterNumber>#{credentials[:meter]}</MeterNumber>
+           </ClientDetail>
+           <TransactionDetail>
+             <CustomerTransactionId>Package Tracker Ruby Gem</CustomerTransactionId>
+           </TransactionDetail>
+           <Version>
+             <ServiceId>trck</ServiceId>
+             <Major>3</Major>
+             <Intermediate>0</Intermediate>
+             <Minor>0</Minor>
+           </Version>
+           <PackageIdentifier>
+             <Value>#{tracking_number}</Value>
+             <Type>TRACKING_NUMBER_OR_DOORTAG</Type>
+           </PackageIdentifier>
+           <IncludeDetailedScans>1</IncludeDetailedScans>
+         </TrackRequest>
+        "
+      end
+
+      def parse_response(tracking_number, response)
+        handle_errors(response)
+
+        tracking_response = Response.new(tracking_number, self)        
+        Nokogiri::XML(response.body).xpath("//v3:Events").each do |event|
+          location = nil
+          unless event.xpath("v3:Address//v3:City").empty?
+            location = "#{event.xpath("v3:Address//v3:City").text}," +
+                       "#{event.xpath("v3:Address//v3:StateOrProvinceCode").text}," + 
+                       "#{event.xpath("v3:Address//v3:CountryCode").text}"
+          end
+          
+          tracking_response.add_status(
+            event.xpath("v3:EventDescription").text,
+            Time.parse(event.xpath("v3:Timestamp").text),
+            location
+          )
+        end
+        tracking_response
+      end
+      
+      def handle_errors(response)
+        document = Nokogiri::XML(response.body)     
+        if document.children.first.namespace.prefix == "ns"
+          raise InvalidCredentialsError if document.xpath("//ns:Notifications//ns:Code").text == "1000"
+        elsif document.children.first.namespace.prefix == "v3"
+          raise InvalidTrackingNumberError if document.xpath("//v3:Notifications//v3:Code").text == "9040"
+        end
+      end
+
+    end
+  end
+end

data/lib/package_tracker/carriers/ups.rb

@@ -0,0 +1,79 @@
+module PackageTracker
+  module Carriers
+    module UPS
+      extend Carrier
+      extend self
+      
+      TEST_URL = "wwwcie.ups.com"
+      LIVE_URL = "www.ups.com"
+      PATH = "/ups.app/xml/Track"
+
+      def track(tracking_number, options)
+        validate_credentials!(options[:credentials])
+        repsonse = Request.post(request_url(options[:testing]), PATH, request_data(tracking_number, options[:credentials]))
+        parse_response(tracking_number, repsonse)
+      end
+      
+      def match(tracking_number)
+        tracking_number =~ /^1Z\d*/
+      end
+    
+      def delivered_status
+        "DELIVERED"
+      end
+  
+      private
+      
+      def request_url(testing)
+        TEST_URL # apparently we don't need the live url for tracking
+      end
+  
+      def required_credentials
+        [:user_id, :key, :password]
+      end
+      
+      def request_data(tracking_number, credentials)
+        "<?xml version='1.0'?>
+          <AccessRequest xml:lang='en-US'>
+            <AccessLicenseNumber>#{credentials[:key]}</AccessLicenseNumber>
+            <UserId>#{credentials[:user_id]}</UserId>
+            <Password>#{credentials[:password]}</Password>
+          </AccessRequest>
+          <?xml version='1.0'?>
+          <TrackRequest xml:lang='en-US'>
+            <Request>
+              <TransactionReference>
+                <XpciVersion>1.0</XpciVersion>
+              </TransactionReference>
+              <RequestAction>Track</RequestAction>
+              <RequestOption>activity</RequestOption>
+            </Request>
+            <TrackingNumber>#{tracking_number}</TrackingNumber>
+          </TrackRequest>
+        "
+      end
+  
+      def parse_response(tracking_number, response)
+        handle_errors(response)
+        
+        tracking_response = Response.new(tracking_number, self)
+        Nokogiri::XML(response.body).css("Package Activity").each do |activity|
+          tracking_response.add_status(
+            activity.css("Status Description").text,
+            Time.parse(activity.css("Date").text) + activity.css("Time").text.to_i,
+            "#{activity.css("City Address").text}, #{activity.css("City StateProvinceCode").text}, #{activity.css("City StateProvinceCode").text}"
+          )
+        end
+        tracking_response
+      end
+      
+      def handle_errors(response)
+        case Nokogiri::XML(response.body).css("Error ErrorCode").text
+          when "250003" then raise InvalidCredentialsError
+          when "151018" then raise InvalidTrackingNumberError
+        end
+      end
+      
+    end
+  end
+end

data/lib/package_tracker/carriers/usps.rb

@@ -0,0 +1,12 @@
+module PackageTracker
+  module Carriers
+    module USPS
+      extend Carrier
+      extend self
+      
+      def match(tracking_number)
+        tracking_number =~ /^\d{20}$/ || tracking_number =~ /^\d{30}$/ || tracking_number =~ /^[A-Za-z]{2}\d{9}[A-Za-z]{2}$/
+      end
+    end
+  end
+end

data/lib/package_tracker/client.rb

@@ -0,0 +1,38 @@
+module PackageTracker
+  class Client
+    attr_accessor :credentials
+    attr_reader :mode
+
+    def initialize(credentials={})
+      @credentials = credentials
+    end
+
+    def track(tracking_number, carrier=nil)
+      # Fed Ex
+      if carrier == :fedex || Carriers::FedEx.match(tracking_number)
+        Carriers::FedEx.track(tracking_number, :credentials => @credentials[:fedex], :testing => testing?)
+      # UPS
+      elsif carrier == :ups || Carriers::UPS.match(tracking_number)
+        Carriers::UPS.track(tracking_number, :credentials => @credentials[:ups], :testing => testing?)
+      # USPS 
+      elsif carrier == :usps || Carriers::USPS.match(tracking_number)
+        raise CarrierNotFoundError, "Need to impliment USPS"
+      # DHL
+      else
+        raise CarrierNotFoundError
+      end
+    end
+        
+    def testing?
+      @mode == "testing"
+    end
+    
+    def test_mode!
+      @mode = "testing"
+    end
+    
+    def production_mode!
+      @mode == "production"
+    end
+  end
+end

data/lib/package_tracker/exceptions.rb

@@ -0,0 +1,16 @@
+module PackageTracker
+  # Generic PackageTracker Error
+  class PackageTrackerError < StandardError; end
+  
+  # Invalid username/password is posted to the server
+  class InvalidCredentialsError < PackageTrackerError; end
+  
+  # The needed credentials to communicate with the server were not given
+  class MissingCredentialsError < PackageTrackerError; end
+    
+  # The tracking number given was invalid
+  class InvalidTrackingNumberError < PackageTrackerError; end
+  
+  # The carrier for the tracking number could not be discerned
+  class CarrierNotFoundError < PackageTrackerError; end
+end

data/lib/package_tracker/request.rb

@@ -0,0 +1,21 @@
+module PackageTracker
+  class Request
+    def self.get(uri, path, body, options={})
+      do_request(Net::HTTP::Get, uri, path, body, options)
+    end
+
+    def self.post(uri, path, body, options={})
+      do_request(Net::HTTP::Post, uri, path, body, options)
+    end
+    
+    def self.do_request(http_method, uri, path, body, options={})      
+      raw_request = http_method.new(path)
+      raw_request.body = body
+      
+      http = Net::HTTP.new(uri, options[:port])
+      http.use_ssl = true if options[:https]
+      
+      http.request(raw_request)
+    end
+  end
+end

data/lib/package_tracker/response.rb

@@ -0,0 +1,32 @@
+module PackageTracker
+  class Response
+    attr_reader :statuses
+    attr_reader :tracking_number
+    
+    def initialize(tracking_number, carrier, statuses=[])
+      @tracking_number = tracking_number
+      @carrier = carrier
+      @statuses = statuses
+      sort_statuses!
+    end
+    
+    def add_status(message, time, location="")
+      @statuses << { :message => message, :time => time, :location => location }
+      sort_statuses!
+    end
+        
+    def current_status
+      @statuses.first
+    end
+    
+    def delivered?
+      current_status[:message] == @carrier.delivered_status
+    end
+    
+    private
+    
+    def sort_statuses!
+      @statuses.sort_by! { |status| status[:time] }.reverse!
+    end
+  end
+end

data/lib/package_tracker.rb

@@ -0,0 +1,23 @@
+$:.unshift File.dirname(__FILE__)
+
+# Gems
+require 'rubygems'
+require 'nokogiri'
+require 'facets'
+require 'facets/module/cattr'
+
+# Standard Lib
+require 'net/http'
+require 'net/https'
+require 'time'
+require 'uri'
+
+# Local Files
+require 'package_tracker/request'
+require 'package_tracker/response'
+require 'package_tracker/client'
+require 'package_tracker/exceptions'
+require 'package_tracker/carrier'
+require 'package_tracker/carriers/ups'
+require 'package_tracker/carriers/fedex'
+require 'package_tracker/carriers/usps'

data/package_tracker.gemspec

@@ -0,0 +1,93 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{package_tracker}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Michael Taras"]
+  s.date = %q{2011-05-18}
+  s.description = %q{PackageTracker is a ruby gem for fetching the status of a packages(UPS, FedEx, etc...) with a simple API.}
+  s.email = %q{michaeltaras@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".Gemfile",
+    ".autotest",
+    ".document",
+    ".rspec",
+    ".rvmrc",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "lib/package_tracker.rb",
+    "lib/package_tracker/carrier.rb",
+    "lib/package_tracker/carriers/fedex.rb",
+    "lib/package_tracker/carriers/ups.rb",
+    "lib/package_tracker/carriers/usps.rb",
+    "lib/package_tracker/client.rb",
+    "lib/package_tracker/exceptions.rb",
+    "lib/package_tracker/request.rb",
+    "lib/package_tracker/response.rb",
+    "package_tracker.gemspec",
+    "spec/carrier/fedex_spec.rb",
+    "spec/carrier/ups_spec.rb",
+    "spec/carrier_spec.rb",
+    "spec/fixtures/requests/ups/invalid_credentials.xml",
+    "spec/fixtures/requests/ups/invalid_tracking_number.xml",
+    "spec/fixtures/requests/ups/valid.xml",
+    "spec/fixtures/responses/fedex/invalid_credentials.xml",
+    "spec/fixtures/responses/fedex/invalid_tracking_number.xml",
+    "spec/fixtures/responses/fedex/valid.xml",
+    "spec/fixtures/responses/ups/invalid_credentials.xml",
+    "spec/fixtures/responses/ups/invalid_tracking_number.xml",
+    "spec/fixtures/responses/ups/valid.xml",
+    "spec/request_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/michaeltaras/package_tracker}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{PackageTracker is a ruby gem for fetching the status of a packages(UPS, FedEx, etc...) with a simple API.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<nokogiri>, [">= 0"])
+      s.add_runtime_dependency(%q<facets>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.0"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.6.0"])
+      s.add_development_dependency(%q<webmock>, [">= 0"])
+    else
+      s.add_dependency(%q<nokogiri>, [">= 0"])
+      s.add_dependency(%q<facets>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.0"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<rspec>, ["~> 2.6.0"])
+      s.add_dependency(%q<webmock>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<nokogiri>, [">= 0"])
+    s.add_dependency(%q<facets>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.0"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<rspec>, ["~> 2.6.0"])
+    s.add_dependency(%q<webmock>, [">= 0"])
+  end
+end
+