trackerific 0.7.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c6ebc05677cc3553211222baad840e0a77f75e0d
-  data.tar.gz: e2f65f8425c2e70a7a6b56c71946b1174337dc5d
+  metadata.gz: 1310f1dbf143518a58178390a664b23b697cadba
+  data.tar.gz: 709ab9cdaa8df43975eff61b797b98586fab4e34
 SHA512:
-  metadata.gz: a789ef97d405deac2bfdfa850cd7a39719a7f6ac64f1e16297098f1e48ed18385bedda51154acdc7a44e3ac6ca4093a3acf543d8d426a062861142d14748cae2
-  data.tar.gz: 532c75fddf2c6b8e4c34abe4822edf52ac41b1e70952cc0cfda368d7ad5869ff32e416a83a2a2ae8a6b31abb9abf09cb342012c6ea3ef73c3e73c6f3c8837485
+  metadata.gz: b398a2bfaab2602d8cb0624d48f7936750abb13bdfb36828a27cd4ec1f4b0a5a0763996de30edf2aa38a4270fecb31e5158a77a2d242542a3c3be6d1094b0158
+  data.tar.gz: dfe45ddfe2c76098a2e9b6c917f6b825fb91d993f92236f9b5b28595f539b48b13d758bae1dbe1fd6ede6928ea202b95638d010ac0cf6e5b06ef81e930781ded

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "2.0.0"
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-19mode

data/Gemfile.lock

@@ -1,10 +1,11 @@
 PATH
   remote: .
   specs:
-    trackerific (0.7.1)
+    trackerific (0.7.2)
       activesupport
       builder (>= 3.1.4)
       httparty (>= 0.12.0)
+      savon (~> 2.3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -15,19 +16,39 @@ GEM
       multi_json (~> 1.3)
       thread_safe (~> 0.1)
       tzinfo (~> 0.3.37)
+    akami (1.2.0)
+      gyoku (>= 0.4.0)
+      nokogiri (>= 1.4.0)
     atomic (1.1.14)
     builder (3.2.2)
+    coveralls (0.7.0)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
     diff-lcs (1.1.3)
     fakeweb (1.3.0)
+    gyoku (1.1.0)
+      builder (>= 2.1.2)
     httparty (0.12.0)
       json (~> 1.8)
       multi_xml (>= 0.5.2)
+    httpi (2.1.0)
+      rack
+      rubyntlm (~> 0.3.2)
     i18n (0.6.5)
     json (1.8.0)
+    mime-types (1.25)
     minitest (4.7.5)
     multi_json (1.8.2)
     multi_xml (0.5.5)
+    nokogiri (1.5.10)
+    nori (2.3.0)
+    rack (1.5.2)
     rake (10.1.0)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
     rspec (2.6.0)
       rspec-core (~> 2.6.0)
       rspec-expectations (~> 2.6.0)
@@ -36,15 +57,36 @@ GEM
     rspec-expectations (2.6.0)
       diff-lcs (~> 1.1.2)
     rspec-mocks (2.6.0)
+    rubyntlm (0.3.4)
+    savon (2.3.0)
+      akami (~> 1.2.0)
+      builder (>= 2.1.2)
+      gyoku (~> 1.1.0)
+      httpi (~> 2.1.0)
+      nokogiri (>= 1.4.0, < 1.6)
+      nori (~> 2.3.0)
+      wasabi (~> 3.2.0)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    term-ansicolor (1.2.2)
+      tins (~> 0.8)
+    thor (0.18.1)
     thread_safe (0.1.3)
       atomic
+    tins (0.12.0)
     tzinfo (0.3.38)
+    wasabi (3.2.0)
+      httpi (~> 2.0)
+      nokogiri (>= 1.4.0, < 1.6)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (>= 1.3.5)
+  coveralls (~> 0.7.0)
   fakeweb (~> 1.3.0)
   rake
   rspec (~> 2.6.0)

data/README.rdoc

@@ -1,3 +1,25 @@
+= 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
@@ -7,24 +29,15 @@ and then run
 
 === Configuration
 
-You will need to configure your credentials for each service:
+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',
-                  :use_city_state_lookup => true
+    config.fedex  = { account: 'account', meter: '123456789' }
+    config.ups    = { key: 'key', user_id: 'userid', password: 'secret' }
+    config.usps   = { user_id: 'userid' }
   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
@@ -36,64 +49,47 @@ Once you configured the services, tracking a package is as easy as
 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("183689015000001")    # => Trackerific::Services::FedEx
-  Trackerific::Services.find_by_tracking_id("1Z12345E0291980793") # => Trackerific::Services::UPS
-  Trackerific::Services.find_by_tracking_id("EJ958083578US")      # => Trackerific::Services::USPS
-  Trackerific::Services.find_by_tracking_id("unknown package id") # => nil
+  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.
 
-  # Track a FedEx package:
-  details = Trackerific::Services::FedEx.track('183689015000001')
-
-  # Track a USPS package:
-  details = Trackerific::Services::USPS.track('EJ958083578US')
+  details = Trackerific::Services::FedEx.track('123456789012')
 
-  # Track a UPS package:
-  details = Trackerific::Services::UPS.track('1Z12345E0291980793')
+Using #track will automatically read the credentials from Trackerific.config.
+If you need to assign them manually, use #new:
 
-Using #track will automatically read the credentials from
-`Trackerific.configuration`. If you need to assign them manually, use #new:
-
-  fedex = Trackerific::Services::FedEx.new account: "account", meter: "123456789"
+  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 # => 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.
+details.summary - Summary of the tracking events
+details.events - Array of Trackerific::Events
 
-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.
+=== Tracking Events
 
-=== City / State Lookup Via USPS
+Tracking::Details has an events Array with the following properties:
 
-If you have access to the USPS CityStateLookup API, you can use Trackerific to
-look up the city and state of a zipcode.
+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.
 
-  usps = Trackerific::Services::USPS.new :user_id => 'userid'
-  usps.city_state_lookup "90210" # => { :city => 'BEVERLY HILLS', :state => 'CA', :zip => '90210' }
+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
 
@@ -115,13 +111,15 @@ 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'
-  details = track_package("XXXXXXXXXX") # => returns a populated Trackerific::Details
-  details = track_package("XXXxxxxxxx") # => throws a Trackerific::Error exception
+  # 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`)
+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

data/lib/trackerific.rb

@@ -1,8 +1,21 @@
+require 'active_support'
+require 'active_support/core_ext/object/to_query'
+require 'securerandom'
+require 'date'
+require 'savon'
+require 'httparty'
+require 'builder'
 require 'trackerific/version'
-require 'trackerific/configuration'
+require 'trackerific/environment'
 require 'trackerific/error'
 require 'trackerific/details'
 require 'trackerific/event'
+require 'trackerific/soap/wsdl'
+require 'trackerific/builders/base/soap'
+require 'trackerific/builders/base/xml'
+require 'trackerific/parsers/base'
+require 'trackerific/services/concerns/soap'
+require 'trackerific/services/concerns/xml'
 require 'trackerific/services'
 require 'trackerific/services/base'
 
@@ -12,32 +25,16 @@ require 'trackerific/services/ups'
 require 'trackerific/services/usps'
 
 module Trackerific
-  class << self
-    # Used to access the Trackerific service credentials
-    # @api public
-    def configuration
-      Trackerific::Configuration.config
-    end
-
-    # Use to configure Trackerific service credentials
-    # @example Configure FedEx credentials
-    #   Trackerific.configure do |config|
-    #     config.fedex account: 'account', meter: '123456789'
-    #   end
-    # @api public
-    def configure(&block)
-      Trackerific::Configuration.configure {|config| yield(config) }
-    end
+  include ActiveSupport::Configurable
 
+  class << self
     # Looks up which service(s) can track the given ID and tracks it.
     # @param [String] id The package identifier
     # @return [Array, Trackerific::Details] The tracking results
     # @raise [Trackerific::Error] Raised when the server returns an error
     # @api public
     def track(id)
-      Trackerific::Services.find_by_package_id(id).map do |service|
-        service.new.track(id)
-      end
+      Trackerific::Services.find_by_package_id(id).map {|s| s.track(id) }
     end
   end
 end

data/lib/trackerific/builders/base/soap.rb

@@ -0,0 +1,21 @@
+module Trackerific
+  module Builders
+    module Base
+      class SOAP < Struct
+        attr_reader :hash
+
+        def initialize(*args)
+          super(*args)
+          @hash = build
+        end
+
+        protected
+
+        def build
+          raise NotImplementedError,
+            "Implement this method in your builder subclass", caller
+        end
+      end
+    end
+  end
+end

data/lib/trackerific/builders/base/xml.rb

@@ -0,0 +1,38 @@
+module Trackerific
+  module Builders
+    module Base
+      class XML < Struct
+        @xml_version = "1.0"
+
+        class << self
+          attr_accessor :xml_version
+        end
+
+        attr_reader :xml
+
+        def initialize(*args)
+          super(*args)
+          @xml = ""
+          build
+        end
+
+        protected
+
+        def build
+          raise NotImplementedError,
+            "Implement this method in your builder subclass", caller
+        end
+
+        private
+
+        def builder
+          @builder ||= begin
+            builder = Builder::XmlMarkup.new(target: @xml)
+            builder.instruct! :xml, version: self.class.xml_version
+            builder
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trackerific/builders/fedex.rb

@@ -0,0 +1,46 @@
+module Trackerific
+  module Builders
+    class FedEx < Base::SOAP.new(:key, :password, :account_number, :meter_number, :package_id)
+      protected
+
+      def build
+        root_elements.inject({}) {|r, k| r[k] = send(k); r }
+      end
+
+      private
+
+      def root_elements
+        [ :web_authentication_detail, :client_detail, :transaction_detail,
+          :version, :selection_details, :processing_options ]
+      end
+
+      def web_authentication_detail
+        { user_credential: { key: key, password: password } }
+      end
+
+      def client_detail
+        { account_number: account_number, meter_number: meter_number }
+      end
+
+      def transaction_detail
+        { customer_transaction_id: "Trackerific" }
+      end
+
+      def version
+        { service_id: 'trck', major: '8', intermediate: '0', minor: '0' }
+      end
+
+      def selection_details
+        { carrier_code: 'FDXE', package_identifier: package_identifier }
+      end
+
+      def package_identifier
+        { type: 'TRACKING_NUMBER_OR_DOORTAG', value: package_id }
+      end
+
+      def processing_options
+        'INCLUDE_DETAILED_SCANS'
+      end
+    end
+  end
+end

data/lib/trackerific/builders/ups.rb

@@ -0,0 +1,32 @@
+module Trackerific
+  module Builders
+    class UPS < Base::XML.new(:key, :user_id, :password, :package_id)
+      protected
+
+      def build
+        add_access_request
+        add_track_request
+      end
+
+      private
+
+      def add_access_request
+        builder.AccessRequest do |ar|
+          ar.AccessLicenseNumber key
+          ar.UserId user_id
+          ar.Password password
+        end
+      end
+
+      def add_track_request
+        builder.TrackRequest do |tr|
+          tr.Request do |r|
+            r.RequestAction 'Track'
+            r.RequestOption 'activity'
+          end
+          tr.TrackingNumber package_id
+        end
+      end
+    end
+  end
+end