trackerific 0.3.1 → 0.3.2
Sign up to get free protection for your applications and to get access to all the features.
- 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
|