trackerific 0.3.1 → 0.3.2
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.
- data/Gemfile +2 -1
- data/Gemfile.lock +5 -1
- data/Rakefile +16 -0
- data/VERSION +1 -1
- data/doc/Trackerific.html +30 -20
- data/doc/Trackerific/Base.html +56 -89
- data/doc/Trackerific/Details.html +84 -33
- data/doc/Trackerific/Error.html +1 -1
- data/doc/Trackerific/Event.html +97 -59
- data/doc/Trackerific/FedEx.html +48 -89
- data/doc/Trackerific/UPS.html +46 -78
- data/doc/Trackerific/USPS.html +56 -145
- data/doc/_index.html +1 -1
- data/doc/file.README.html +1 -1
- data/doc/index.html +1 -1
- data/doc/method_list.html +13 -53
- data/doc/top-level-namespace.html +1 -1
- data/lib/fedex.rb +32 -17
- data/lib/trackerific.rb +41 -10
- data/lib/trackerific_details.rb +22 -3
- data/lib/trackerific_event.rb +27 -7
- data/lib/ups.rb +21 -12
- data/lib/usps.rb +32 -19
- data/spec/lib/trackerific_spec.rb +1 -7
- data/trackerific.gemspec +7 -7
- metadata +21 -7
- data/.yardoc/checksums +0 -6
- data/.yardoc/objects/root.dat +0 -0
- data/.yardoc/proxy_types +0 -0
data/doc/_index.html
CHANGED
@@ -186,7 +186,7 @@
|
|
186
186
|
</div>
|
187
187
|
|
188
188
|
<div id="footer">
|
189
|
-
Generated on Mon Jun 13
|
189
|
+
Generated on Mon Jun 13 16:20:05 2011 by
|
190
190
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
191
191
|
0.7.1 (ruby-1.9.2).
|
192
192
|
</div>
|
data/doc/file.README.html
CHANGED
@@ -206,7 +206,7 @@ Copyright © 2011 Travis Haynes. See LICENSE.txt for further details.
|
|
206
206
|
</div></div>
|
207
207
|
|
208
208
|
<div id="footer">
|
209
|
-
Generated on Mon Jun 13
|
209
|
+
Generated on Mon Jun 13 16:20:05 2011 by
|
210
210
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
211
211
|
0.7.1 (ruby-1.9.2).
|
212
212
|
</div>
|
data/doc/index.html
CHANGED
@@ -206,7 +206,7 @@ Copyright © 2011 Travis Haynes. See LICENSE.txt for further details.
|
|
206
206
|
</div></div>
|
207
207
|
|
208
208
|
<div id="footer">
|
209
|
-
Generated on Mon Jun 13
|
209
|
+
Generated on Mon Jun 13 16:20:05 2011 by
|
210
210
|
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
211
211
|
0.7.1 (ruby-1.9.2).
|
212
212
|
</div>
|
data/doc/method_list.html
CHANGED
@@ -65,9 +65,9 @@
|
|
65
65
|
|
66
66
|
|
67
67
|
<li class="r2 ">
|
68
|
-
<span class='object_link'><a href="Trackerific/
|
68
|
+
<span class='object_link'><a href="Trackerific/Base.html#initialize-instance_method" title="Trackerific::Base#initialize (method)">#initialize</a></span>
|
69
69
|
|
70
|
-
<small>Trackerific::
|
70
|
+
<small>Trackerific::Base</small>
|
71
71
|
|
72
72
|
</li>
|
73
73
|
|
@@ -81,14 +81,6 @@
|
|
81
81
|
|
82
82
|
|
83
83
|
<li class="r2 ">
|
84
|
-
<span class='object_link'><a href="Trackerific/Base.html#initialize-instance_method" title="Trackerific::Base#initialize (method)">#initialize</a></span>
|
85
|
-
|
86
|
-
<small>Trackerific::Base</small>
|
87
|
-
|
88
|
-
</li>
|
89
|
-
|
90
|
-
|
91
|
-
<li class="r1 ">
|
92
84
|
<span class='object_link'><a href="Trackerific/Event.html#initialize-instance_method" title="Trackerific::Event#initialize (method)">#initialize</a></span>
|
93
85
|
|
94
86
|
<small>Trackerific::Event</small>
|
@@ -96,7 +88,7 @@
|
|
96
88
|
</li>
|
97
89
|
|
98
90
|
|
99
|
-
<li class="
|
91
|
+
<li class="r1 ">
|
100
92
|
<span class='object_link'><a href="Trackerific/Event.html#location-instance_method" title="Trackerific::Event#location (method)">#location</a></span>
|
101
93
|
|
102
94
|
<small>Trackerific::Event</small>
|
@@ -104,7 +96,7 @@
|
|
104
96
|
</li>
|
105
97
|
|
106
98
|
|
107
|
-
<li class="
|
99
|
+
<li class="r2 ">
|
108
100
|
<span class='object_link'><a href="Trackerific/Details.html#package_id-instance_method" title="Trackerific::Details#package_id (method)">#package_id</a></span>
|
109
101
|
|
110
102
|
<small>Trackerific::Details</small>
|
@@ -112,32 +104,24 @@
|
|
112
104
|
</li>
|
113
105
|
|
114
106
|
|
115
|
-
<li class="r2 ">
|
116
|
-
<span class='object_link'><a href="Trackerific/USPS.html#required_options-instance_method" title="Trackerific::USPS#required_options (method)">#required_options</a></span>
|
117
|
-
|
118
|
-
<small>Trackerific::USPS</small>
|
119
|
-
|
120
|
-
</li>
|
121
|
-
|
122
|
-
|
123
107
|
<li class="r1 ">
|
124
|
-
<span class='object_link'><a href="Trackerific/
|
108
|
+
<span class='object_link'><a href="Trackerific/Details.html#summary-instance_method" title="Trackerific::Details#summary (method)">#summary</a></span>
|
125
109
|
|
126
|
-
<small>Trackerific::
|
110
|
+
<small>Trackerific::Details</small>
|
127
111
|
|
128
112
|
</li>
|
129
113
|
|
130
114
|
|
131
115
|
<li class="r2 ">
|
132
|
-
<span class='object_link'><a href="Trackerific/
|
116
|
+
<span class='object_link'><a href="Trackerific/Event.html#to_s-instance_method" title="Trackerific::Event#to_s (method)">#to_s</a></span>
|
133
117
|
|
134
|
-
<small>Trackerific::
|
118
|
+
<small>Trackerific::Event</small>
|
135
119
|
|
136
120
|
</li>
|
137
121
|
|
138
122
|
|
139
123
|
<li class="r1 ">
|
140
|
-
<span class='object_link'><a href="Trackerific/UPS.html#
|
124
|
+
<span class='object_link'><a href="Trackerific/UPS.html#track_package-instance_method" title="Trackerific::UPS#track_package (method)">#track_package</a></span>
|
141
125
|
|
142
126
|
<small>Trackerific::UPS</small>
|
143
127
|
|
@@ -145,25 +129,9 @@
|
|
145
129
|
|
146
130
|
|
147
131
|
<li class="r2 ">
|
148
|
-
<span class='object_link'><a href="Trackerific/
|
149
|
-
|
150
|
-
<small>Trackerific::Details</small>
|
151
|
-
|
152
|
-
</li>
|
153
|
-
|
154
|
-
|
155
|
-
<li class="r1 ">
|
156
|
-
<span class='object_link'><a href="Trackerific/Event.html#to_s-instance_method" title="Trackerific::Event#to_s (method)">#to_s</a></span>
|
157
|
-
|
158
|
-
<small>Trackerific::Event</small>
|
159
|
-
|
160
|
-
</li>
|
161
|
-
|
162
|
-
|
163
|
-
<li class="r2 ">
|
164
|
-
<span class='object_link'><a href="Trackerific/Base.html#track_package-instance_method" title="Trackerific::Base#track_package (method)">#track_package</a></span>
|
132
|
+
<span class='object_link'><a href="Trackerific/USPS.html#track_package-instance_method" title="Trackerific::USPS#track_package (method)">#track_package</a></span>
|
165
133
|
|
166
|
-
<small>Trackerific::
|
134
|
+
<small>Trackerific::USPS</small>
|
167
135
|
|
168
136
|
</li>
|
169
137
|
|
@@ -177,22 +145,14 @@
|
|
177
145
|
|
178
146
|
|
179
147
|
<li class="r2 ">
|
180
|
-
<span class='object_link'><a href="Trackerific/
|
148
|
+
<span class='object_link'><a href="Trackerific/Base.html#track_package-instance_method" title="Trackerific::Base#track_package (method)">#track_package</a></span>
|
181
149
|
|
182
|
-
<small>Trackerific::
|
150
|
+
<small>Trackerific::Base</small>
|
183
151
|
|
184
152
|
</li>
|
185
153
|
|
186
154
|
|
187
155
|
<li class="r1 ">
|
188
|
-
<span class='object_link'><a href="Trackerific/USPS.html#track_package-instance_method" title="Trackerific::USPS#track_package (method)">#track_package</a></span>
|
189
|
-
|
190
|
-
<small>Trackerific::USPS</small>
|
191
|
-
|
192
|
-
</li>
|
193
|
-
|
194
|
-
|
195
|
-
<li class="r2 ">
|
196
156
|
<span class='object_link'><a href="Trackerific.html#tracking_service-instance_method" title="Trackerific#tracking_service (method)">#tracking_service</a></span>
|
197
157
|
|
198
158
|
<small>Trackerific</small>
|
data/lib/fedex.rb
CHANGED
@@ -4,41 +4,41 @@ module Trackerific
|
|
4
4
|
|
5
5
|
# Provides package tracking support for FedEx
|
6
6
|
class FedEx < Base
|
7
|
+
# setup HTTParty
|
7
8
|
include ::HTTParty
|
8
9
|
format :xml
|
9
10
|
base_uri "https://gateway.fedex.com"
|
10
11
|
|
11
|
-
#
|
12
|
-
#
|
13
|
-
def required_options
|
14
|
-
[:account, :meter]
|
15
|
-
end
|
16
|
-
|
17
|
-
# Tracks a FedEx package.
|
18
|
-
#
|
19
|
-
# A Trackerific::Error is raised when a package cannot be tracked.
|
20
|
-
#
|
12
|
+
# Tracks a FedEx package
|
13
|
+
# @param [String] package_id the package identifier
|
21
14
|
# @return [Trackerific::Details] the tracking details
|
15
|
+
# @raise [Trackerific::Error] raised when the server returns an error (invalid credentials, tracking package, etc.)
|
16
|
+
# @example Track a package
|
17
|
+
# fedex = Trackerific::FedEx.new :account => 'account', :meter => 'meter'
|
18
|
+
# details = fedex.track_package("183689015000001")
|
19
|
+
# @api public
|
22
20
|
def track_package(package_id)
|
23
21
|
super
|
22
|
+
# request tracking information from FedEx via HTTParty
|
24
23
|
http_response = self.class.post "/GatewayDC", :body => build_xml_request
|
24
|
+
# raise any HTTP errors
|
25
25
|
http_response.error! unless http_response.code == 200
|
26
|
-
|
26
|
+
# get the tracking information from the reply
|
27
27
|
track_reply = http_response["FDXTrack2Reply"]
|
28
|
+
# raise a Trackerific::Error if there is an error in the reply
|
28
29
|
raise Trackerific::Error, track_reply["Error"]["Message"] unless track_reply["Error"].nil?
|
29
|
-
|
30
|
+
# get the details from the reply
|
30
31
|
details = track_reply["Package"]
|
32
|
+
# convert them into Trackerific::Events
|
31
33
|
events = []
|
32
34
|
details["Event"].each do |e|
|
33
35
|
date = Time.parse("#{e["Date"]} #{e["Time"]}")
|
34
36
|
desc = e["Description"]
|
35
37
|
addr = e["Address"]
|
36
|
-
# Adds event in this format:
|
37
|
-
# MM DD HH:MM am/pm Description City State Zip
|
38
38
|
events << Trackerific::Event.new(date, desc, "#{addr["StateOrProvinceCode"]} #{addr["PostalCode"]}")
|
39
39
|
end
|
40
|
-
|
41
|
-
Details.new(
|
40
|
+
# Return a Trackerific::Details containing all the events
|
41
|
+
Trackerific::Details.new(
|
42
42
|
details["TrackingNumber"],
|
43
43
|
details["StatusDescription"],
|
44
44
|
events
|
@@ -47,15 +47,30 @@ module Trackerific
|
|
47
47
|
|
48
48
|
protected
|
49
49
|
|
50
|
+
# Returns an Array of required options used when creating a new instance
|
51
|
+
# @return [Array] required options for tracking a FedEx package are :account
|
52
|
+
# and :meter
|
53
|
+
# @api private
|
54
|
+
def required_options
|
55
|
+
[:account, :meter]
|
56
|
+
end
|
57
|
+
|
50
58
|
# Builds the XML request to send to FedEx
|
51
59
|
# @return [String] a FDXTrack2Request XML
|
60
|
+
# @api private
|
52
61
|
def build_xml_request
|
53
62
|
xml = ""
|
63
|
+
# the API namespace
|
54
64
|
xmlns_api = "http://www.fedex.com/fsmapi"
|
65
|
+
# the XSI namespace
|
55
66
|
xmlns_xsi = "http://www.w3.org/2001/XMLSchema-instance"
|
67
|
+
# the XSD namespace
|
56
68
|
xsi_noNSL = "FDXTrack2Request.xsd"
|
69
|
+
# create a new Builder to generate the XML
|
57
70
|
builder = ::Builder::XmlMarkup.new(:target => xml)
|
71
|
+
# add the XML header
|
58
72
|
builder.instruct! :xml, :version => "1.0", :encoding => "UTF-8"
|
73
|
+
# Build, and return the request
|
59
74
|
builder.FDXTrack2Request "xmlns:api"=>xmlns_api, "xmlns:xsi"=>xmlns_xsi, "xsi:noNamespaceSchemaLocation" => xsi_noNSL do |r|
|
60
75
|
r.RequestHeader do |rh|
|
61
76
|
rh.AccountNumber @options[:account]
|
@@ -66,7 +81,7 @@ module Trackerific
|
|
66
81
|
end
|
67
82
|
r.DetailScans true
|
68
83
|
end
|
69
|
-
|
84
|
+
xml
|
70
85
|
end
|
71
86
|
|
72
87
|
end
|
data/lib/trackerific.rb
CHANGED
@@ -9,40 +9,71 @@ module Trackerific
|
|
9
9
|
|
10
10
|
# Base class for Trackerific package tracking services.
|
11
11
|
class Base
|
12
|
+
# Creates a new instance of Trackerific::Base with required options
|
13
|
+
# @api private
|
12
14
|
def initialize(options = {})
|
13
15
|
required = required_options
|
16
|
+
# make sure all the required options exist
|
14
17
|
required.each do |k|
|
15
18
|
raise ArgumentError.new("Missing required parameter: #{k}") unless options.has_key?(k)
|
16
19
|
end
|
20
|
+
# make sure no invalid options exist
|
17
21
|
options.each do |k, v|
|
18
22
|
raise ArgumentError.new("Invalid parameter: #{k}") unless required.include?(k)
|
19
23
|
end
|
20
24
|
@options = options
|
21
25
|
end
|
22
26
|
|
23
|
-
#
|
27
|
+
# Gets the tracking information for the package from the server
|
28
|
+
# @param [String] package_id the package identifier
|
29
|
+
# @return [Trackerific::Details] the tracking details
|
30
|
+
# @example Override this method in your custom tracking provider to implement tracking
|
31
|
+
# module Trackerific
|
32
|
+
# class MyTrackingProvider < Base
|
33
|
+
# def track_package
|
34
|
+
# Trackerific::Details.new(
|
35
|
+
# "summary of tracking events",
|
36
|
+
# [Trackerific::Event.new(Time.now, "summary", "location")]
|
37
|
+
# )
|
38
|
+
# end
|
39
|
+
# end
|
40
|
+
# end
|
41
|
+
# @api public
|
42
|
+
def track_package(package_id)
|
43
|
+
@package_id = package_id
|
44
|
+
end
|
45
|
+
|
46
|
+
protected
|
47
|
+
|
48
|
+
# An array of options that are required to create a new instance of this class
|
24
49
|
# @return [Array] the required options
|
50
|
+
# @example Override this method in your custom tracking provider to enforce some options
|
51
|
+
# module Trackerific
|
52
|
+
# class MyTrackingProvider < Base
|
53
|
+
# def required_options
|
54
|
+
# [:all, :these, :are, :required]
|
55
|
+
# end
|
56
|
+
# end
|
57
|
+
# end
|
58
|
+
# @api private
|
25
59
|
def required_options
|
26
60
|
[]
|
27
61
|
end
|
28
62
|
|
29
|
-
# Override this method in your subclass to implement tracking a package.
|
30
|
-
# @return [Hash] the tracking details
|
31
|
-
def track_package(package_id)
|
32
|
-
@package_id = package_id
|
33
|
-
end
|
34
63
|
end
|
35
64
|
|
36
65
|
require 'usps'
|
37
66
|
require 'fedex'
|
38
67
|
require 'ups'
|
39
68
|
|
40
|
-
# Checks a string for a valid package
|
41
|
-
#
|
42
|
-
#
|
43
|
-
# @param [String] the package identifier.
|
69
|
+
# Checks a string for a valid package tracking service
|
70
|
+
# @param [String] package_id the package identifier
|
44
71
|
# @return [Trackerific::Base] the Trackerific class that can track the given
|
45
72
|
# package id, or nil if none found.
|
73
|
+
# @example Find out which service provider will track a valid FedEx number
|
74
|
+
# include Trackerific
|
75
|
+
# tracking_service "183689015000001" # => Trackerific::FedEx
|
76
|
+
# @api public
|
46
77
|
def tracking_service(package_id)
|
47
78
|
case package_id
|
48
79
|
when /^.Z/, /^[HK].{10}$/ then Trackerific::UPS
|
data/lib/trackerific_details.rb
CHANGED
@@ -3,26 +3,45 @@ module Trackerific
|
|
3
3
|
# a summary, and the events.
|
4
4
|
class Details
|
5
5
|
# Provides a new instance of Details
|
6
|
-
# @param [String] the package identifier
|
7
|
-
# @param [String] a summary of the tracking status
|
8
|
-
# @param [Array, Trackerific::Event] the tracking events
|
6
|
+
# @param [String] package_id the package identifier
|
7
|
+
# @param [String] summary a summary of the tracking status
|
8
|
+
# @param [Array, Trackerific::Event] events the tracking events
|
9
|
+
# @api private
|
9
10
|
def initialize(package_id, summary, events)
|
10
11
|
@package_id = package_id
|
11
12
|
@summary = summary
|
12
13
|
@events = events
|
13
14
|
end
|
14
15
|
|
16
|
+
# Read-only string for the package identifier
|
17
|
+
# @example Get the id of a tracked package
|
18
|
+
# details.package_id # => the package identifier
|
15
19
|
# @return [String] the package identifier
|
20
|
+
# @api public
|
16
21
|
def package_id
|
17
22
|
@package_id
|
18
23
|
end
|
19
24
|
|
25
|
+
# Read-only string for the summary of the package's tracking events
|
26
|
+
# @example Get the summary of a tracked package
|
27
|
+
# details.summary # => Summary of the tracking events (i.e. Delivered)
|
20
28
|
# @return [String] a summary of the tracking status
|
29
|
+
# @api public
|
21
30
|
def summary
|
22
31
|
@summary
|
23
32
|
end
|
24
33
|
|
34
|
+
# Read-only string for the events for this package
|
35
|
+
# @example Print all the events for a tracked package
|
36
|
+
# puts details.events
|
37
|
+
# @example Get the date the package was shipped
|
38
|
+
# details.events.last.date # => a DateTime value
|
39
|
+
# @example A bulleted HTML list of the events (most current on top) in haml
|
40
|
+
# %ul
|
41
|
+
# - details.events.each do |event|
|
42
|
+
# %li= event
|
25
43
|
# @return [Array, Trackerific::Event] the tracking events
|
44
|
+
# @api public
|
26
45
|
def events
|
27
46
|
@events
|
28
47
|
end
|
data/lib/trackerific_event.rb
CHANGED
@@ -2,32 +2,52 @@ module Trackerific
|
|
2
2
|
# Provides details for a tracking event
|
3
3
|
class Event
|
4
4
|
# Provides a new instance of Event
|
5
|
-
# @param [Time] the date / time of the event
|
6
|
-
# @param [String] the event's description
|
7
|
-
# @param [String] where the event took place
|
5
|
+
# @param [Time] date the date / time of the event
|
6
|
+
# @param [String] description the event's description
|
7
|
+
# @param [String] location where the event took place
|
8
|
+
# @api private
|
8
9
|
def initialize(date, description, location)
|
9
10
|
@date = date
|
10
11
|
@description = description
|
11
12
|
@location = location
|
12
13
|
end
|
13
14
|
|
14
|
-
#
|
15
|
+
# The date and time of the event
|
16
|
+
# @example Get the date of an event
|
17
|
+
# date = details.events.first.date
|
18
|
+
# @return [DateTime]
|
19
|
+
# @api public
|
15
20
|
def date
|
16
21
|
@date
|
17
22
|
end
|
18
23
|
|
19
|
-
#
|
24
|
+
# The event's description
|
25
|
+
# @example Get the description of an event
|
26
|
+
# description = details.events.first.description
|
27
|
+
# @return [String]
|
28
|
+
# @api public
|
20
29
|
def description
|
21
30
|
@description
|
22
31
|
end
|
23
32
|
|
24
|
-
#
|
25
|
-
#
|
33
|
+
# Where the event took place (usually in City State Zip format)
|
34
|
+
# @example Get the location of an event
|
35
|
+
# location = details.events.first.location
|
36
|
+
# @return [String]
|
37
|
+
# @api public
|
26
38
|
def location
|
27
39
|
@location
|
28
40
|
end
|
29
41
|
|
42
|
+
# Converts the event into a string
|
43
|
+
# @example Get a human-readable string from an event
|
44
|
+
# event = details.event.to_s
|
45
|
+
# @example A bulleted list of events in haml
|
46
|
+
# %ul
|
47
|
+
# - details.events.each do |event|
|
48
|
+
# %li= event
|
30
49
|
# @return [String] converts the event into a string
|
50
|
+
# @api public
|
31
51
|
def to_s
|
32
52
|
dte = self.date.strftime('%b %d %I:%M %P')
|
33
53
|
des = self.description
|