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/doc/_index.html CHANGED
@@ -186,7 +186,7 @@
186
186
  </div>
187
187
 
188
188
  <div id="footer">
189
- Generated on Mon Jun 13 14:22:51 2011 by
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 &#169; 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 14:22:51 2011 by
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 &#169; 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 14:22:51 2011 by
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/USPS.html#initialize-instance_method" title="Trackerific::USPS#initialize (method)">#initialize</a></span>
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::USPS</small>
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="r2 ">
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="r1 ">
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/Base.html#required_options-instance_method" title="Trackerific::Base#required_options (method)">#required_options</a></span>
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::Base</small>
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/FedEx.html#required_options-instance_method" title="Trackerific::FedEx#required_options (method)">#required_options</a></span>
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::FedEx</small>
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#required_options-instance_method" title="Trackerific::UPS#required_options (method)">#required_options</a></span>
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/Details.html#summary-instance_method" title="Trackerific::Details#summary (method)">#summary</a></span>
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::Base</small>
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/UPS.html#track_package-instance_method" title="Trackerific::UPS#track_package (method)">#track_package</a></span>
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::UPS</small>
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>
@@ -94,7 +94,7 @@
94
94
  </div>
95
95
 
96
96
  <div id="footer">
97
- Generated on Mon Jun 13 14:22:52 2011 by
97
+ Generated on Mon Jun 13 16:20:06 2011 by
98
98
  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
99
99
  0.7.1 (ruby-1.9.2).
100
100
  </div>
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
- # @return [Array] required options for tracking a FedEx package are :account
12
- # and :meter.
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
- return xml
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
- # Override this method if your subclass has required options.
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 identifier, and returns a Trackerific
41
- # class that should be able to track the package.
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
@@ -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
@@ -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
- # @return [Time] the date / time of the event
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
- # @return [String] the event's description.
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
- # @return [String] where the event took place (usually in City State Zip
25
- # format)
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