RubyGems - trackerific - Versions diffs - 0.2.1 → 0.3.0 - Mend

trackerific 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

data/.yardoc/checksums +6 -0
data/.yardoc/objects/root.dat +0 -0
data/.yardoc/proxy_types +0 -0
data/VERSION +1 -1
data/doc/Trackerific.html +258 -0
data/doc/Trackerific/Base.html +390 -0
data/doc/Trackerific/Details.html +514 -0
data/doc/Trackerific/Error.html +127 -0
data/doc/Trackerific/Event.html +601 -0
data/doc/Trackerific/FedEx.html +395 -0
data/doc/Trackerific/UPS.html +360 -0
data/doc/Trackerific/USPS.html +453 -0
data/doc/_index.html +195 -0
data/doc/class_list.html +47 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +53 -0
data/doc/css/style.css +320 -0
data/doc/file.README.html +213 -0
data/doc/file_list.html +49 -0
data/doc/frames.html +13 -0
data/doc/index.html +213 -0
data/doc/js/app.js +205 -0
data/doc/js/full_list.js +150 -0
data/doc/js/jquery.js +16 -0
data/doc/method_list.html +206 -0
data/doc/top-level-namespace.html +103 -0
data/lib/fedex.rb +17 -7
data/lib/trackerific.rb +16 -2
data/lib/trackerific_details.rb +30 -0
data/lib/trackerific_event.rb +38 -0
data/lib/ups.rb +40 -14
data/lib/usps.rb +28 -5
data/spec/lib/fedex_spec.rb +8 -10
data/spec/lib/trackerific_details_spec.rb +19 -0
data/spec/lib/trackerific_event_spec.rb +20 -0
data/spec/lib/ups_spec.rb +8 -6
data/spec/lib/usps_spec.rb +8 -10
data/trackerific.gemspec +32 -1
metadata +35 -4

data/doc/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,103 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.7.1
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  relpath = '';
+  if (relpath != '') relpath += '/';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <script type="text/javascript" charset="utf-8">
+      if (window.top.frames.main) document.body.className = 'frames';
+    </script>
+    <div id="header">
+      <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
+</div>
+      <div id="search">
+    <a id="class_list_link" href="#">Class List</a>
+    <a id="method_list_link" href="#">Method List</a>
+    <a id="file_list_link" href="#">File List</a>
+</div>
+      <div class="clear"></div>
+    </div>
+    <iframe id="search_frame"></iframe>
+    <div id="content"><h1>Top Level Namespace
+</h1>
+<dl class="box">
+</dl>
+<div class="clear"></div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Trackerific.html" title="Trackerific (module)">Trackerific</a></span>
+</p>
+</div>
+    <div id="footer">
+  Generated on Mon Jun 13 13:53:34 2011 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.7.1 (ruby-1.9.2).
+</div>
+  </body>
+</html>

data/lib/fedex.rb CHANGED Viewed

@@ -2,15 +2,23 @@ require 'httparty'
 module Trackerific
+  # Provides package tracking support for FedEx
   class FedEx < Base
     include ::HTTParty
     format :xml
     base_uri "https://gateway.fedex.com"
+    # @return [Array] required options for tracking a FedEx package are :account
+    #   and :meter.
     def required_options
       [:account, :meter]
     end
+    # Tracks a FedEx package.
+    #
+    # A Trackerific::Error is raised when a package cannot be tracked.
+    #
+    # @return [Trackerific::Details] the tracking details
     def track_package(package_id)
       super
       http_response = self.class.post "/GatewayDC", :body => build_xml_request
@@ -22,23 +30,25 @@ module Trackerific
       details = track_reply["Package"]
       events = []
       details["Event"].each do |e|
-        date = Time.parse("#{e["Date"]} #{e["Time"]}").strftime('%b %d %I:%M %P')
+        date = Time.parse("#{e["Date"]} #{e["Time"]}")
         desc = e["Description"]
         addr = e["Address"]
         # Adds event in this format:
         # MM DD HH:MM am/pm Description City State Zip
-        events << "#{date} #{desc} #{addr["City"]} #{addr["StateOrProvinceCode"]} #{addr["PostalCode"]}"
+        events << Trackerific::Event.new(date, desc, "#{addr["StateOrProvinceCode"]} #{addr["PostalCode"]}")
       end
-      return {
-        :package_id => details["TrackingNumber"],
-        :summary    => details["StatusDescription"],
-        :details    => events
-      }
+      Details.new(
+        details["TrackingNumber"],
+        details["StatusDescription"],
+        events
+      )
     end
     protected
+    # Builds the XML request to send to FedEx
+    # @return [String] a FDXTrack2Request XML
     def build_xml_request
       xml = ""
       xmlns_api = "http://www.fedex.com/fsmapi"

data/lib/trackerific.rb CHANGED Viewed

@@ -1,9 +1,13 @@
+# Trackerific is a UPS, FedEx and USPS tracking provider.
 module Trackerific
   require 'rails'
+  require 'trackerific_details'
+  require 'trackerific_event'
-  class Error < StandardError
-  end
+  # Raised if something other than tracking information is returned.
+  class Error < StandardError; end
+  # Base class for Trackerific package tracking services.
   class Base
     def initialize(options = {})
       required = required_options
@@ -16,10 +20,14 @@ module Trackerific
       @options = options
     end
+    # Override this method if your subclass has required options.
+    # @return [Array] the required options
     def required_options
       []
     end
+    # Override this method in your subclass to implement tracking a package.
+    # @return [Hash] the tracking details
     def track_package(package_id)
       @package_id = package_id
     end
@@ -29,6 +37,12 @@ module Trackerific
   require 'fedex'
   require 'ups'
+  # Checks a string for a valid package identifier, and returns a Trackerific
+  # class that should be able to track the package.
+  #
+  # @param [String] the package identifier.
+  # @return [Trackerific::Base] the Trackerific class that can track the given
+  #   package id, or nil if none found.
   def tracking_service(package_id)
     case package_id
       when /^.Z/, /^[HK].{10}$/ then Trackerific::UPS

data/lib/trackerific_details.rb ADDED Viewed

@@ -0,0 +1,30 @@
+module Trackerific
+  # Details returned when tracking a package. Stores the package identifier,
+  # a summary, and the events.
+  class Details
+    # Provides a new instance of Details
+    # @param [String] the package identifier
+    # @param [String] a summary of the tracking status
+    # @param [Array, Trackerific::Event] the tracking events
+    def initialize(package_id, summary, events)
+      @package_id = package_id
+      @summary = summary
+      @events = events
+    end
+    # @return [String] the package identifier
+    def package_id
+      @package_id
+    end
+    # @return [String] a summary of the tracking status
+    def summary
+      @summary
+    end
+    # @return [Array, Trackerific::Event] the tracking events
+    def events
+      @events
+    end
+  end
+end

data/lib/trackerific_event.rb ADDED Viewed

@@ -0,0 +1,38 @@
+module Trackerific
+  # Provides details for a tracking event
+  class Event
+    # Provides a new instance of Event
+    # @param [Time] the date / time of the event
+    # @param [String] the event's description
+    # @param [String] where the event took place
+    def initialize(date, description, location)
+      @date = date
+      @description = description
+      @location = location
+    end
+    # @return [Time] the date / time of the event
+    def date
+      @date
+    end
+    # @return [String] the event's description.
+    def description
+      @description
+    end
+    # @return [String] where the event took place (usually in City State Zip
+    #   format)
+    def location
+      @location
+    end
+    # @return [String] converts the event into a string
+    def to_s
+      dte = self.date.strftime('%b %d %I:%M %P')
+      des = self.description
+      loc = self.location
+      "#{dte} #{des} #{loc}"
+    end
+  end
+end

data/lib/ups.rb CHANGED Viewed

@@ -1,6 +1,9 @@
+require 'date'
 module Trackerific
   require 'httparty'
+  # Provides package tracking support for UPS.
   class UPS < Base
     include ::HTTParty
     format :xml
@@ -9,14 +12,25 @@ module Trackerific
       when 'production' then 'https://www.ups.com/ups.app/xml'
     end : 'https://www.ups.com/ups.app/xml'
+    # The required options for tracking a UPS package are :key, :user_id, and
+    # :password.
+    #
+    # @return [Array] the required options for tracking a UPS package.
     def required_options
       [:key, :user_id, :password]
     end
+    # Tracks a UPS package.
+    # A Trackerific::Error is raised when a package cannot be tracked.
+    # @return [Trackerific::Details] the tracking details
     def track_package(package_id)
       super
+      # connect to UPS via HTTParty
       http_response = self.class.post('/Track', :body => build_xml_request)
+      # throw any HTTP errors
       http_response.error! unless http_response.code == 200
+      # Check the response for errors, return a Trackerific::Error, or parse
+      # the response from UPS and return a Trackerific::Details
       case http_response['TrackResponse']['Response']['ResponseStatusCode']
         when "0" then raise Trackerific::Error, parse_error_response(http_response)
         when "1" then return parse_success_response(http_response)
@@ -26,32 +40,44 @@ module Trackerific
     protected
+    # Parses the response from UPS
+    # @return [Trackerific::Details]
     def parse_success_response(http_response)
+      # get the activity from the UPS response
       activity = http_response['TrackResponse']['Shipment']['Package']['Activity']
+      # if there's only one activity in the list, we need to put it in an array
       activity = [activity] if activity.is_a? Hash
+      # UPS does not provide a summary, so we'll just use the last tracking status
+      summary = activity.first['Status']['StatusType']['Description'].titleize
       details = []
       activity.each do |a|
-        status = a['Status']['StatusType']['Description']
-        if status != "UPS INTERNAL ACTIVITY CODE"
-          address = a['ActivityLocation']['Address'].map {|k,v| v}.join(" ")
-          date = "#{a['Date'].to_date} #{a['Time'][0..1]}:#{a['Time'][2..3]}:#{a['Time'][4..5]}".to_datetime
-          details << "#{date.strftime('%b %d %I:%M %P')} #{status}"
-        end
+        # the time format from UPS is HHMMSS, which cannot be directly converted
+        # to a Ruby time.
+        hours   = a['Time'][0..1]
+        minutes = a['Time'][2..3]
+        seconds = a['Time'][4..5]
+        date    = Date.parse(a['Date'])
+        date    = DateTime.parse("#{date} #{hours}:#{minutes}:#{seconds}")
+        desc    = a['Status']['StatusType']['Description'].titleize
+        loc     = a['ActivityLocation']['Address'].map {|k,v| v}.join(" ")
+        details << Trackerific::Event.new(date, desc, loc)
       end
-      # UPS does not provide a summary, so just use the last tracking details
-      summary = details.last
-      details.delete(summary)
-      return {
-        :package_id => @package_id,
-        :summary => summary,
-        :details => details.reverse
-      }
+      Trackerific::Details.new(
+        @package_id,
+        summary,
+        details
+      )
     end
+    # Parses a UPS tracking response, and returns any errors.
+    # @return [String] the UPS tracking error
     def parse_error_response(http_response)
       http_response['TrackResponse']['Response']['Error']['ErrorDescription']
     end
+    # Builds the XML request to send to UPS for tracking a package.
+    # @return [String] the XML request
     def build_xml_request
       xml = ""
       builder = ::Builder::XmlMarkup.new(:target => xml)

data/lib/usps.rb CHANGED Viewed

@@ -1,7 +1,10 @@
+require 'date'
 module Trackerific
   require 'builder'
   require 'httparty'
+  # Provides package tracking support for USPS.
   class USPS < Base
     include HTTParty
     format :xml
@@ -15,10 +18,16 @@ module Trackerific
       @options = options
     end
+    # The required option for tracking a UPS package is :user_id
+    #
+    # @return [Array] the required options for tracking a UPS package.
     def required_options
       [:user_id]
     end
+    # Tracks a USPS package.
+    # A Trackerific::Error is raised when a package cannot be tracked.
+    # @return [Trackerific::Details] the tracking details
     def track_package(package_id)
       super
       response = self.class.get('/ShippingAPITest.dll', :query => {:API => 'TrackV2', :XML => build_xml_request}.to_query)
@@ -26,15 +35,29 @@ module Trackerific
       raise Trackerific::Error, response['Error']['Description'] unless response['Error'].nil?
       raise Trackerific::Error, "Tracking information not found in response from server." if response['TrackResponse'].nil?
       tracking_info = response['TrackResponse']['TrackInfo']
-      {
-        :package_id => tracking_info['ID'],
-        :summary => tracking_info['TrackSummary'],
-        :details => tracking_info['TrackDetail']
-      }
+      details = []
+      tracking_info['TrackDetail'].each do |d|
+        # each tracking detail is a string in this format:
+        # MM DD HH:MM am/pm DESCRIPTION CITY STATE ZIP.
+        # unfortunately, it will not be possible to tell the difference between
+        # the location, and the summary. So, for USPS, the location will be in
+        # the summary
+        d = d.split(" ")
+        date = DateTime.parse(d[0..3].join(" "))
+        desc = d[4..d.length].join(" ")
+        details << Trackerific::Event.new(date, desc, "")
+      end
+      Trackerific::Details.new(
+        tracking_info['ID'],
+        tracking_info['TrackSummary'],
+        details
+      )
     end
     protected
+    # Parses the response from UPS
+    # @return [Trackerific::Details]
     def build_xml_request
       tracking_request = ""
       builder = ::Builder::XmlMarkup.new(:target => tracking_request)

data/spec/lib/fedex_spec.rb CHANGED Viewed

@@ -19,17 +19,15 @@ describe "Trackerific::FedEx" do
           FEDEX_TRACK_URL,
           :body => load_fixture(:fedex_success_response)
         )
-        @valid_response = {
-          :package_id => "183689015000001",
-          :summary    => "Delivered",
-          :details    => [
-            "Jul 01 10:43 am Delivered Gainesville GA 30506",
-            "Jul 01 08:48 am On FedEx vehicle for delivery ATHENS GA 30601",
-            "Jul 01 05:07 am At local FedEx facility ATHENS GA 30601"
-          ]
-        }
+        @tracking = @fedex.track_package(@package_id)
+      end
+      specify { @tracking.should be_a Trackerific::Details }
+      it "should have at least one event" do
+        @tracking.events.length.should >= 1
+      end
+      it "should have a summary" do
+        @tracking.summary.should_not be_empty
       end
-      specify { @fedex.track_package(@package_id).should eq @valid_response }
     end
     context "with an error response from the server" do
       before(:all) do