awesome_usps 0.5.0 → 0.6.0

data/History.txt

@@ -2,3 +2,12 @@
 
 * 1 major enhancement:
   * Initial release
+
+== 0.6.0 18/8/2008
+
+* 2 major improvement
+  *	Shipping parse fixed
+  * Documentation added
+* 1 bug fixes
+  * Shipping canned tests fixed
+  

data/License.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2008 FIXME full name
+Copyright (c) 2008 Matthew Bergman
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/PostInstall.txt

@@ -1,7 +1,7 @@
+To use Awesome! USPS in your app use require 'awesome_USPS' in your environment.rb or production.rb
 
 For more information on awesome_usps, see http://awesome_usps.rubyforge.org
 
-NOTE: Change this information in PostInstall.txt 
-You can also delete it if you don't want it.
+
 
 

data/README.txt

@@ -26,7 +26,7 @@ FIX (describe your package)
 
 (The MIT License)
 
-Copyright (c) 2008 FIXME full name
+Copyright (c) 2008 Matthew Bergman
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/awesome_usps.rb

@@ -12,8 +12,7 @@ require 'awesome_usps/electric_merchandis_return'
 require 'awesome_usps/express_mail'
 require 'awesome_usps/address_verification'
 require 'awesome_usps/international_mail_labels'
-
-
+include AwesomeUsps
 
 module AwesomeUsps
   class USPS

data/lib/awesome_usps/shipping.rb

@@ -1,30 +1,17 @@
 module AwesomeUsps
   module Shipping
 
-    MAX_RETRIES = 3
 
-    ORIGIN_ZIP = "07024" #User should change this
+    MAX_RETRIES = 3
 
     LIVE_DOMAIN = 'production.shippingapis.com'
     LIVE_RESOURCE = '/ShippingAPI.dll'
 
-    TEST_DOMAINS = { #indexed by security; e.g. TEST_DOMAINS[USE_SSL[:rates]]
-      true => 'secure.shippingapis.com',
-      false => 'testing.shippingapis.com'
-    }
-
-    TEST_RESOURCE = '/ShippingAPITest.dll'
-
     API_CODES = {
       :us_rates => 'RateV3',
       :world_rates => 'IntlRate',
-      :test => 'CarrierPickupAvailability'
     }
 
-    USE_SSL = {
-      :tracking => false,
-      :test => true
-    }
     CONTAINERS = {
       :envelope => 'Flat Rate Envelope',
       :box => 'Flat Rate Box'
@@ -62,21 +49,12 @@ module AwesomeUsps
       :all => 'ALL'
     }
 
-    #Determins size of package automatically. Taken from Active_Shipping
-    def size_code_for(package)
-      total = package.inches(:length) + package.inches(:girth)
-      if total <= 84
-        return 'REGULAR'
-      elsif total <= 108
-        return 'LARGE'
-      else # <= 130
-        return 'OVERSIZE'
-      end
-    end
 
     # options Are?
-    def domestic_rates(destination_zip, packages, options={})
-      @packages = Array(packages)
+    def domestic_rates(origin_zip, destination_zip, packages, options={})
+      @origin_zip = origin_zip
+      @packages = packages
+      Array(@packages)  if not @packages.is_a? Array
       @destination_zip = destination_zip
       @options = options
       request = xml_for_us
@@ -85,14 +63,62 @@ module AwesomeUsps
 
     # options Are?
     def world_rates(country, packages, options={})
-      @packages = Array(packages)
+      @packages = packages
+      Array(@packages)  if not @packages.is_a? Array
       @country = country
       @options = options
       request = xml_for_world
       tracking_commit(:world_rates, request ,false)
     end
-    
+
+    def canned_domestic_rates_test
+      @origin_zip = "07024"
+      @packages =[
+        Package.new(  100,
+        [93,10],
+        :cylinder => true),
+
+        Package.new(  (7.5 * 16),
+        [15, 10, 4.5],
+        :units => :imperial)
+      ]
+      @destination_zip = "10010"
+      @options = {}
+      request = xml_for_us
+      tracking_commit(:us_rates, request ,false)
+    end
+
+
+    def canned_world_rates_test
+      @packages =  [
+        Package.new(  100,
+        [93,10],
+        :cylinder => true),
+
+        Package.new(  (7.5 * 16),
+        [15, 10, 4.5],
+        :units => :imperial)
+      ]
+      @country = "Japan"
+      @options ={}
+      request = xml_for_world
+      tracking_commit(:world_rates, request ,false)
+    end
+
     private
+
+    #Determins size of package automatically. Taken from Active_Shipping
+    def size_code_for(package)
+      total = package.inches(:length) + package.inches(:girth)
+      if total <= 84
+        return 'REGULAR'
+      elsif total <= 108
+        return 'LARGE'
+      else # <= 130
+        return 'OVERSIZE'
+      end
+    end
+
     # XML built with Build:XmlMarkup
     def xml_for_us
       xm = Builder::XmlMarkup.new
@@ -101,7 +127,7 @@ module AwesomeUsps
           p = @packages[id]
           xm.Package("ID" => "#{id}") {
             xm.Service("#{US_SERVICES[@options[:service]] || :all}")
-            xm.ZipOrigination(ORIGIN_ZIP)
+            xm.ZipOrigination(@origin_zip)
             xm.ZipDestination(@destination_zip)
             xm.Pounds("0")
             xm.Ounces("#{'%0.1f' % [p.ounces,1].max}")
@@ -142,9 +168,10 @@ module AwesomeUsps
     # {Package1 =>{'First Class' => "1.90"}Package2 => {'First Class' => "26.90" }
 
     def parse_us(xml)
-      domestic_rate_hash = Hash.new
-      i= 0
+      i=0
+      domestic_rate_array = []
       Hpricot.parse(xml).search('package').each do |package|
+        h = {}
         i+=1
         #This will return the first error description found in response xml.
         #TODO find way to return all errors.
@@ -153,26 +180,27 @@ module AwesomeUsps
 
           return "package number #{i} has the error #{package.search("description").inner_html} please fix before continuing"
         end
-        #Initializing hash for each package. Is there a better way I wonder.
-        domestic_rate_hash["Package#{i}"] = {}
         #Going through each package and finding the rate.
         package.search("postage").each do |services|
+
           mailservice=services.search("mailservice")
           rate = services.search("rate")
-          domestic_rate_hash["Package#{i}"][mailservice.inner_html] = rate.inner_html
+          h[mailservice.inner_html] = rate.inner_html
         end
+        domestic_rate_array << h
       end
-      if domestic_rate_hash == {}
-        domestic_rate_hash = Hpricot.parse(xml).search('description').inner_html
+      if  domestic_rate_array == []
+        return Hpricot.parse(xml).search('description').inner_html
       end
-      return domestic_rate_hash
+      return domestic_rate_array
     end
-    
+
     def parse_world(xml)
-      international_rate_hash = Hash.new
+      international_rate_array = []
       i= 0
       Hpricot.parse(xml).search('package').each do |package|
         i+=1
+        h = {}
         #This will return the first error description found in response xml.
         #TODO find way to return all errors.
         if package.search("error") != []
@@ -180,19 +208,20 @@ module AwesomeUsps
 
           return "package number #{i} has the error #{package.search("description").inner_html} please fix before continuing"
         end
-        #Initializing hash for each package. Is there a better way I wonder.
-        international_rate_hash["Package#{i}"] = {}
         #Going through each package and finding the rate.
         package.search("service").each do |services|
+
           svcdescription=services.search("svcdescription")
           rate = services.search("postage")
-          international_rate_hash["Package#{i}"][svcdescription.inner_html] = rate.inner_html
+          h[svcdescription.inner_html] = rate.inner_html
+
         end
+        international_rate_array << h
       end
-      if international_rate_hash == {}
-        international_rate_hash = Hpricot.parse(xml).search('description').inner_html
+      if   international_rate_array == []
+        return Hpricot.parse(xml).search('description').inner_html
       end
-      return international_rate_hash
+      return international_rate_array
     end
 
     def tracking_commit(action, request, test = false)
@@ -202,8 +231,8 @@ module AwesomeUsps
         req = Net::HTTP::Post.new(url.path)
         req.set_form_data({'API' => API_CODES[action], 'XML' => request})
         response = Net::HTTP.new(url.host, url.port)
-        response.open_timeout = 5
-        response.read_timeout = 5
+        response.open_timeout = 2
+        response.read_timeout = 2
         response.start
       rescue Timeout::Error
         if retries > 0
@@ -233,4 +262,3 @@ module AwesomeUsps
     end
   end
 end
-

data/lib/awesome_usps/version.rb

@@ -1,7 +1,7 @@
 module AwesomeUsps
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 5
+    MINOR = 6
     TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')

data/website/index.html

@@ -33,7 +33,7 @@
     <h1></h1>
     <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/awesome_usps"; return false'>
       <p>Get Version</p>
-      <a href="http://rubyforge.org/projects/awesome_usps" class="numbers">0.5.0</a>
+      <a href="http://rubyforge.org/projects/awesome_usps" class="numbers">0.6.0</a>
     </div>
     <h1>Awesome! <span class="caps">USPS</span> <br/> &#x2192; &#8216;awesome_usps&#8217;</h1>
 
@@ -41,7 +41,7 @@
 	<h2>What</h2>
 
 
-	<p>A Ruby Wrapper for a variety of <span class="caps">USPS</span> APIs. Including Tracking and Rate calculation.</p>
+	<p>This library is meant to interface with the web services of <span class="caps">USPS</span>. It grew out of early dabbling of the <span class="caps">USPS</span>_Tracker plugin. The goal is to abstract the features that are most frequently used into a pleasant and consistent Ruby <span class="caps">API</span>. Awesome <span class="caps">USPS</span> started as an extension of Active Shipping but at the moment I am still struggling with how best to accomplish integration. While working on the problem I decided to release my current work as a gem for all to enjoy.</p>
 
 
 	<h2>Installing</h2>
@@ -66,47 +66,406 @@
 	<p>From there use how you like in your  controllers.</p>
 
 
-	<h2>Demonstration of usage</h2>
+	<h2>Prerequisites</h2>
 
 
-	<h2>Forum</h2>
+	<p><a href="http://code.whytheluckystiff.net/hpricot/">Hrpicot</a> for parsing the <span class="caps">XML</span>. To install run sudo gem install Hpricot</p>
 
 
-	<p><a href="http://groups.google.com/group/awesome_usps">http://groups.google.com/group/awesome_usps</a></p>
+	<p><a href="http://mocha.rubyforge.org/">Mocha</a> for the tests</p>
 
 
-	<p><span class="caps">TODO</span> &#8211; create Google Group &#8211; awesome_usps</p>
+	<h2>Notice about using the <span class="caps">USPS</span> APIs</h2>
 
 
-	<h2>How to submit patches</h2>
+	<p><span class="caps">USPS</span> can be a bit frustrating when starting working with them. First you must apply for a <span class="caps">USPS</span> web tools account
+This will net you a <span class="caps">USPS</span> user name assigned by them and a password. The password is for older versions of their api so you do not need to concern yourself with it. 
+Secondly you only have accesses to the Testing Server. You should run one of the canned response to make sure everything is setup up correctly.</p>
 
 
-	<p>You can fetch the source from either:</p>
+	<p>usps.canned_tracking</p>
+
+
+	<p>You should receive an array as a response. 
+From there you need to email <span class="caps">USPS</span> for your account to be changed over to production so you can send live data. This does not hold true for all their Api some of which require and additional level of clearance. See Below</p>
+
+
+	<h2>Notice on <span class="caps">USPS</span> Label APIs</h2>
+
+
+	<p><span class="caps">USPS</span> is kinda&#8230; bad with how they handle their various label creation APIs. Except for their Priority Mail&#174; Open and Distribute <span class="caps">API</span> you must make an additional email or call to their customer care center to have your permission turned on to send live data to the server. It is even more complicated if you wish to create your own labels with your company logo from their response xml. See their <span class="caps">API</span> documentation located at
+ for details on the procedure.</p>
+
+
+	<h2>Notice on Address Information APIs</h2>
+
+
+	<p>These APIs; Specifically Address Verify, Zip Lookup, and City State Lookup also need separate permission for use of live data.</p>
+
+
+	<h2>Canned Tests</h2>
+
+
+	<p>Because most of the <span class="caps">API</span>&#8217;s require an additional level of permission to use with live data every method has a canned test. They are both useful for integrating the returned data with your system and for testing that the library has not been compromised. A canned method follow this format. canned_method_name_test.</p>
+
+
+	<h2>Awesome <span class="caps">USPS</span> methods</h2>
+
+
+	<p><span class="caps">API</span> methods are as follow</p>
 
 
 	<ul>
-	<li>rubyforge: <span class="caps">MISSING IN ACTION</span></li>
+	<li>track</li>
+		<li>veryify_address</li>
+		<li>zip_lookup</li>
+		<li>city_state_lookup</li>
+		<li>delivery_confirmation_label</li>
+		<li>signature_confirmation_label</li>
+		<li>merch_return</li>
+		<li>express_mail</li>
+		<li>express_mail_international_label</li>
+		<li>priority_mail_international_label</li>
+		<li>first_class_international_label</li>
+		<li>open_distrubute_priority_label</li>
+		<li>priority_mail_estimated_time</li>
+		<li>standard_mail_estimated_time</li>
+		<li>domestic_rates</li>
+		<li>world_rates</li>
 	</ul>
 
 
-	<p><span class="caps">TODO</span> &#8211; You can not created a RubyForge project, OR have not run <code>rubyforge config</code>
-yet to refresh your local rubyforge data with this projects&#8217; id information.</p>
+	<p>Object Methods are as follow</p>
+
+
+	<p>Package.new
+Location.new
+International Location #Only used in conjunction with international labels <span class="caps">API</span></p>
+
+
+	<h1 class="smallish">Sample Usage</h1>
+
+
+	<p>In your environment.rb or production.rb</p>
+
+
+<pre>require 'active_shipping'</pre>
+
+ Then to access the plugin you much create an instance of <span class="caps">USPS</span> class
+
+<pre> usps = USPS.new('Your user name')</pre>
+
+	<p>Package up a poster and a Wii for your nephew.<br/>
+<small>Note the Package Module has been taken directly from Active Shipping. Thank you James MacAulay for developing such great code. </small></p>
+
+
+<pre>packages = [
+  Package.new(  100,                        # 100 grams
+                [93,10],                    # 93 cm long, 10 cm diameter
+                :cylinder =&gt; true),         # cylinders have different volume calculations
+  Package.new(  (7.5 * 16),                 # 7.5 lbs, times 16 oz/lb.
+                [15, 10, 4.5],              # 15x10x4.5 inches
+                :units =&gt; :imperial)        # not grams, not centimetres
+]</pre>
+
+	<p>Create a location to use with the Api</p>
+
+
+<pre>sender =Location.new(:name =&gt; "Matthew Bergman ",:first_name =&gt; "Matthew", :last_name =&gt; "Bergman",
+:address1 =&gt; Apt 4m, :address2 =&gt; "1001 Pine Street", 
+:city =&gt; "New York", :state =&gt; "NY", :zip5 =&gt; "100010", :phone =&gt; "5555555555")</pre>
+
+	<p>International Item Class<br/>
+<small>Only should be used in conjunction with the Internal Label Api </small>
+<pre>
+Items = [
+    InternationalItem.new( 
+    :description =&gt; Pens", 
+    :quantity =&gt; "50" 
+    :value =&gt; 200.40,                       #Will be converted back to a float if entered as a string. 
+    :ounces =&gt; "50",                            
+    :tariff_number =&gt; "Only use if known"   #Optional input for the api. 
+    :country =&gt; "United States")
+    InternationalItem.new( 
+    :description =&gt; "Against The Day, Pynchon",
+    :quantity =&gt; "10" 
+    :value =&gt; 100.25
+    :ounces =&gt; "250" 
+    :country =&gt; "United States")
+]
+</pre></p>
+
+
+	<h3>Note for working with Location Class</h3>
+
+
+	<p>The api is very quirky about how it handles addresses. :address1 is for inputing Apt or Suite numbers and nothing else. 
+Besides the obvious info, it can contain, :facility_type and :from_urbanization, which are used for specific APIs.</p>
+
+
+	<h2>To track a package</h2>
+
+
+<pre>USPS.track("Tracking Number")
+#This will return an array of tracking events example shown below
+
+[{:eventzipcode=&gt;"33436", :event=&gt;"Arrival at Unit", :eventtime=&gt;"7:23 am", :eventdate=&gt;"June 14, 2008",
+ :eventcity=&gt;"BOYNTON BEACH", :eventstate=&gt;"FL"},
+ {:eventzipcode=&gt;"32862", :event=&gt;"Processed", :eventtime=&gt;"9:50 pm", 
+ :eventdate=&gt;"June 13, 2008", :eventcity=&gt;"ORLANDO",    :eventstate=&gt;"FL"},
+ {:eventzipcode=&gt;"07032", :event=&gt;"Processed", :eventtime=&gt;"1:19 am",
+ :eventdate=&gt;"June 13, 2008", :eventcity=&gt;"KEARNY",     :eventstate=&gt;"NJ"},
+ {:eventzipcode=&gt;"07024", :event=&gt;"Acceptance", :eventtime=&gt;"3:03 pm", :eventdate=&gt;"June 12, 
+ 2008", :eventcity=&gt;"FORT LEE", :eventstate=&gt;"NJ"}]
+
+#Loop through and display as you wish
+</pre>
+
+	<h2>To get rates for a single or group of packages.</h2>
+
+
+<pre>#There are two APIs. One for domestic, the other for international packages.
+
+USPS.domestic_rates(ZIP, Packages, options={})
+USPS.world_rates(Country, Packages, options={})
+
+#Both will return and array containg a hash of rates for each package.
+#To access a rate hash for use you can do 
+
+array = USPS.world_rates(Country, Packages, options={})
+array[0][Priority Mail International
+
+#You can also loop through and sort
+</pre>
 
+	<h2>Address Verification</h2>
 
-	<p>When you do this, this message will magically disappear!</p>
 
+<pre>#All methods here will take a location array of up to five address
 
-	<p>Or you can hack website/index.txt and make it all go away!!</p>
+#To verify an address and fill in missing information. 
+#If mulitple addresses were found for an address :verified =&gt; false
+
+usps.veryify_address("locations array")
+
+#Will fill in missing zip5 and zip4 for an address
+usps.zipcode_lookup("location array")
+
+#Will fill in missing City and State for an address
+usps.city_state_lookup
+</pre>
+
+	<h2>Service Standards</h2>
+
+
+<pre>usps.priority_mail_estimated_time(origin, destination)
+
+usps.standard_mail_estimated_time(origin, destination)
+
+#Both of these methods returns a number for the amount of days a package will take to reach 
+#its destination.
+</pre>
+
+	<h2>Express Mail Commitment</h2>
+
+
+<pre>usps.express_mail_commitment(origin, destination, date=nil)
+
+#returns a array of hashs containing commitment information. Example shown below
+[{:state=&gt;"MD", :cutoff=&gt;"6:00 PM", :facility=&gt;"EXPRESS MAIL COLLECTION BOX", :zip=&gt;"20770", 
+:street=&gt;"119 CENTER WAY", :city=&gt;"GREENBELT"}, {:state=&gt;"MD", :cutoff=&gt;"3:00 PM", 
+:facility=&gt;"EXPRESS MAIL COLLECTION BOX", :zip=&gt;"20770", :street=&gt;"7500 GREENWAY CENTER DRIVE", 
+:city=&gt;"GREENBELT"}]
+</pre>
+
+	<h1 class="smallish">Label APIs</h1>
+
+
+	<p>All label <span class="caps">API</span>&#8217;s generate a label image  encoded via 64bit encryption. It must be decrypted by using  
+Base64.decode64(Image_file) to display correctly. The only choices for image_type right now are pdf and <span class="caps">TIFF</span>
+An easy way to test and intergrate is to set up something along these lines in a controller.</p>
+
+
+<pre>
+def deliver_confirmation
+    image = USPS.new("XXXXXX").canned_delivery_confirmation_label_test
+    send_data Base64.decode64(image[:label]), :type =&gt; image[:image_type], :disposition =&gt; "inline" 
+end
+</pre>
+
+	<p>All labels except for international labels take a straight name for their <span class="caps">XML</span>. 
+When using International label APIs you must include both a first and last name</p>
+
+
+	<h2>Delivery and Signature Label Creation</h2>
+
+
+<pre>usps.delivery_confirmation_label(origin, destination, service_type, image_type, label_type=1, options={})
+usps.signature_confirmation_label(origin, destination, service_type, image_type, label_type=1, options={}) 
+
+#label_type can be set to 2 if you desire to create your own labels. No label will be generated for you,
+#you simply will receive a  confirmation label to use with the image you create. 
+
+#Option hash can contain
+
+* :weight_in_ounces 
+* :seperate =&gt; puts the label directions on a seperate page. 
+* :po_zip_code =&gt; Post Offic zip code
+* :label_date =&gt; Can be set up to four days in the future
+* :customer_reference_number
+* :address_service =&gt; ill be notified in the future if address has been changed
+* :sender_name, :sender_email, 
+  :recipient_name, :recipient_email  =&gt; Used together to send an email to the recipient.
+
+</pre>
+
+	<h2>Electronic Merchandise Return Label Creation</h2>
+
+
+<pre>usps.merch_return(service_type, customer, retailer, permit_number, 
+                  post_office, postage_delivery_unit,  ounces, image_type, options={})
+#permit_number =&gt; Input permit number provided by your local post office.
+#post_office =&gt; Location class of post office that issued the permit. Address not needed
+#postage_delivery_unit =&gt; Location class for delivery unit you are sending the package to.
+
+#Option hash can contain
+
+ * :confirmation =&gt; "Includes delivery confirmation with the label. To enable set to true" 
+ * :insurance_value 
+ * :rma =&gt; "Return Materials Authorization Number" 
+ * :RMABarcode =&gt; "Will Render Barcode on Label if set to true and a RMA has been entered" 
+ * :sender_name, :sender_email, 
+   :recipient_name, :recipient_email  =&gt; Used together to send an email to the recipient. 
+
+#Output hash contains postnet number and the cost for sending. Under :postnet and :cost respectively.
+</pre>
+
+	<h2>Express Mail Label Creation</h2>
+
+
+<pre>usps.express_mail_label(orgin, destination, ounces, image_type, options={})
+
+#Option hash can contain
+
+ * :flat_rate =&gt; "Can be set to true if using flat rate envelopes" 
+ * :standardize_address =&gt; "Verify Address" 
+ * :waiver_signature =&gt; "No Signature Required for Delivery" 
+ * :no_holiday =&gt; "Do not deliver on a holiday" 
+ * :no_weekend
+ * :seperate =&gt; puts the label directions on a seperate page
+ * :po_zip_code
+ * :label_date  =&gt; Can be set up to four days in the future
+ * :sender_name, :sender_email, 
+   :recipient_name, :recipient_email  =&gt; Used together to send an email to the recipient. 
+
+#Output hash contains postage cost for sending. Can be accessed by :postage
+</pre>
+
+	<h2>International Mail Labels Creation</h2>
+
+
+<pre>usps.express_mail_international_label(sender, receiver, items, image_type, po_box_flag ="N",
+image_layout="ALLINONEFILE", label_type="1", options={})
+
+usps.priority_mail_international_label(sender, receiver, items, image_type, po_box_flag ="N",
+image_layout="ALLINONEFILE", label_type="1", options={})
+
+usps.first_class_international_label(sender, receiver, items, image_type, po_box_flag ="N",
+image_layout="ALLINONEFILE", label_type="1", options={})
+
+#label_type can be set to 2 if you desire to create your own labels. No label will be generated for you,
+#items =&gt; InternationalItem.new can be an array of objects or singular
+#content_type =&gt; Options are "MERCHANDISE", "SAMPLE", "GIFT", "DOCUMENTS", "RETURN", "OTHER" 
+#If OTHER is selected content type must be described by :other =&gt; "Description" in the option hash.
+#image_layout =&gt; "Allows for a few options" 
+#po_box_flag  can be set to "Y" if items are being sent to a PO-Box
+
+Option Hash for priority and express can contain
+
+ * :middle_initial =&gt; "middle initial of sender" 
+ * :from_customs_reference
+ * :to_customs_reference
+ * :fax =&gt; "fax of receiver" 
+ * :email =&gt; "email of receiver" 
+ * :non_delivery_option =&gt; "Return, Reject, Abaddon. Defaults to abaddon." 
+ * :alt_return_address1 =&gt; "used to explain where package goes 
+    if delivery_option set to . Goes up to alt_return_address6" 
+ * :alt_return_country
+ * :container =&gt; "VARIABLE or FLATRATEENV" 
+ * :insurance_number
+ * :Postage =&gt; "If postage is already known. Will be caculated if left blank. " 
+ * :other
+ * :comments
+ * :license_number
+ * :certificate_number
+ * :invoice_number
+ * :reference_number
+ * :po_zip_code
+ * :label_date  =&gt; Can be set up to four days in the future
+ * :hold =&gt; "Hold for manifest" 
+Option Hash for first_class can contain
+ * :middle_initial =&gt; "middle initial of sender" 
+ * :from_customs_reference
+ * :to_customs_reference
+ * :fax =&gt; "fax of receiver" 
+ * :email =&gt; "email of receiver" 
+ * :first_class_mail_type
+ * :machinable =&gt; "True or False" 
+ * :other
+ * :comments
+ * :label_date  =&gt; Can be set up to four days in the future
+ * :hold =&gt; "Hold for manifest" 
+
+#Output hash contains postage cost, total value of all items, SDRValue and the Bar code number.
+#Can be access :postage, :totalvalue, :sdrvalue, and :barcodenumber respectively. 
+</pre>
+
+	<h2>Open Distribute Priority Label Creation</h2>
+
+
+<pre>#TODO a good description for what Open Distribute Priority actually means
+usps.open_distrubute_priority_label(orgin, destination, 
+     package_weight_in_ounces, mail_type, image_type, label_type=1, options={})
+
+#label_type can be set to 2 if you desire to create your own labels. No label will be generated for you,
+#you simply will receive a  confirmation label to use with the image you create.
+#destination class must contain :facility_type, See API Document for explination of the different types
+#mail_type can be be, "Letters", "Flats", "Parcels", "Mixed" or "Other" 
+#If other is chosen it must be described in the option hash via :other =&gt; "Description" 
+
+#Option has can contain
+ * :permit_number =&gt; "Issued by Post Office" 
+ * :permit_zip =&gt; "Zip of Post Office that issued permit. Must be included if using :permit_number" 
+ * :po_zip_code
+ * :other
+ * :no_weekend
+ * :seperate =&gt; puts the label directions on a seperate page
+ * :label_date  =&gt; Can be set up to four days in the future
+</pre>
+
+	<h2>Forum</h2>
+
+
+	<p><a href="http://groups.google.com/group/awesome_usps">http://groups.google.com/group/awesome_usps</a></p>
+
+
+	<p><span class="caps">TODO</span> &#8211; create Google Group &#8211; awesome_usps</p>
+
+
+	<h2>How to submit patches</h2>
+
+
+	<p>You can fetch the source from either:</p>
 
 
 	<ul>
-	<li>github: <a href="http://github.com/fotoverite/awesome_usps/tree/master">http://github.com/fotoverite/awesome_usps/tree/master</a></li>
+	<li>rubyforge: <a href="http://rubyforge.org/scm/?group_id=6811">http://rubyforge.org/scm/?group_id=6811</a></li>
 	</ul>
 
 
-<pre>git clone git://github.com/fotoverite/awesome_usps.git</pre>
+<pre>git clone git://rubyforge.org/awesome_usps.git</pre>
 
-	<p><span class="caps">TODO</span> &#8211; add &#8220;github_username: username&#8221; to ~/.rubyforge/user-config.yml and newgem will reuse it for future projects.</p>
+	<p>or</p>
 
 
 	<ul>
@@ -134,7 +493,7 @@ rake install_gem</pre>
 
 	<p>Comments are welcome. Send an email to <a href="mailto:Fotoverite">Matthew Bergman</a> email via the <a href="http://groups.google.com/group/awesome_usps">forum</a></p>
     <p class="coda">
-      <a href="FIXME email">FIXME full name</a>, 15th August 2008<br>
+      <a href="FotoVerite@gmail.com">Matthew Bergman</a>, 16th August 2008<br>
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
     </p>
 </div>

data/website/index.txt

@@ -5,7 +5,7 @@ h1. Awesome! USPS <br/> &#x2192; 'awesome_usps'
 
 h2. What
 
-A Ruby Wrapper for a variety of USPS APIs. Including Tracking and Rate calculation. 
+This library is meant to interface with the web services of USPS. It grew out of early dabbling of the USPS_Tracker plugin. The goal is to abstract the features that are most frequently used into a pleasant and consistent Ruby API. Awesome USPS started as an extension of Active Shipping but at the moment I am still struggling with how best to accomplish integration. While working on the problem I decided to release my current work as a gem for all to enjoy.
 
 h2. Installing
 
@@ -23,46 +23,359 @@ Create an instance of the USPS class in your application.rb
 
 From there use how you like in your  controllers. 
 
-h2. Demonstration of usage
+h2. Prerequisites
 
+"Hrpicot":http://code.whytheluckystiff.net/hpricot/ for parsing the XML. To install run sudo gem install Hpricot
 
+"Mocha":http://mocha.rubyforge.org/ for the tests
 
-h2. Forum
+h2. Notice about using the USPS APIs
 
-"http://groups.google.com/group/awesome_usps":http://groups.google.com/group/awesome_usps
+USPS can be a bit frustrating when starting working with them. First you must apply for a USPS web tools account
+This will net you a USPS user name assigned by them and a password. The password is for older versions of their api so you do not need to concern yourself with it. 
+Secondly you only have accesses to the Testing Server. You should run one of the canned response to make sure everything is setup up correctly. 
 
-TODO - create Google Group - awesome_usps
+usps.canned_tracking
 
-h2. How to submit patches
+You should receive an array as a response. 
+From there you need to email USPS for your account to be changed over to production so you can send live data. This does not hold true for all their Api some of which require and additional level of clearance. See Below
 
-You can fetch the source from either:
+h2. Notice on USPS Label APIs
 
-<% if rubyforge_project_id %>
+USPS is kinda... bad with how they handle their various label creation APIs. Except for their Priority Mail(R) Open and Distribute API you must make an additional email or call to their customer care center to have your permission turned on to send live data to the server. It is even more complicated if you wish to create your own labels with your company logo from their response xml. See their API documentation located at
+[http://www.http://www.usps.com/webtools/htm/Delivery-Confirmation.htm]:http://www.usps.com/webtools/htm/Delivery-Confirmation.htm for details on the procedure.
 
-* rubyforge: "http://rubyforge.org/scm/?group_id=<%= rubyforge_project_id %>":http://rubyforge.org/scm/?group_id=<%= rubyforge_project_id %>
+h2. Notice on Address Information APIs
 
-<pre>git clone git://rubyforge.org/awesome_usps.git</pre>
+These APIs; Specifically Address Verify, Zip Lookup, and City State Lookup also need separate permission for use of live data. 
+
+h2. Canned Tests
+
+Because most of the API's require an additional level of permission to use with live data every method has a canned test. They are both useful for integrating the returned data with your system and for testing that the library has not been compromised. A canned method follow this format. canned_method_name_test. 
+
+h2. Awesome USPS methods
+
+API methods are as follow
+
+* track
+* veryify_address
+* zip_lookup
+* city_state_lookup
+* delivery_confirmation_label
+* signature_confirmation_label
+* merch_return
+* express_mail
+* express_mail_international_label
+* priority_mail_international_label
+* first_class_international_label
+* open_distrubute_priority_label
+* priority_mail_estimated_time
+* standard_mail_estimated_time
+* domestic_rates
+* world_rates
+
+Object Methods are as follow
+
+Package.new
+Location.new
+International Location #Only used in conjunction with international labels API
+
+h1(smallish). Sample Usage
+
+In your environment.rb or production.rb
+
+<pre>require 'active_shipping'</pre>
+
+ Then to access the plugin you much create an instance of USPS class
+
+<pre> usps = USPS.new('Your user name')</pre>
+
+Package up a poster and a Wii for your nephew.<br/>
+<small>Note the Package Module has been taken directly from Active Shipping. Thank you James MacAulay for developing such great code. </small>
+
+<pre>packages = [
+  Package.new(  100,                        # 100 grams
+                [93,10],                    # 93 cm long, 10 cm diameter
+                :cylinder => true),         # cylinders have different volume calculations
+  Package.new(  (7.5 * 16),                 # 7.5 lbs, times 16 oz/lb.
+                [15, 10, 4.5],              # 15x10x4.5 inches
+                :units => :imperial)        # not grams, not centimetres
+]</pre>
+
+Create a location to use with the Api
+
+<pre>sender =Location.new(:name => "Matthew Bergman ",:first_name => "Matthew", :last_name => "Bergman",
+:address1 => Apt 4m, :address2 => "1001 Pine Street", 
+:city => "New York", :state => "NY", :zip5 => "100010", :phone => "5555555555")</pre>
+
+International Item Class<br/>
+<small>Only should be used in conjunction with the Internal Label Api </small>
+<pre>
+Items = [
+    InternationalItem.new( 
+    :description => Pens", 
+    :quantity => "50" 
+    :value => 200.40,                       #Will be converted back to a float if entered as a string. 
+    :ounces => "50",                            
+    :tariff_number => "Only use if known"   #Optional input for the api. 
+    :country => "United States")
+    InternationalItem.new( 
+    :description => "Against The Day, Pynchon",
+    :quantity => "10"
+    :value => 100.25
+    :ounces => "250"
+    :country => "United States")
+]
+</pre>
 
-<% else %>
+h3. Note for working with Location Class
 
-* rubyforge: MISSING IN ACTION
+The api is very quirky about how it handles addresses. :address1 is for inputing Apt or Suite numbers and nothing else. 
+Besides the obvious info, it can contain, :facility_type and :from_urbanization, which are used for specific APIs.
 
-TODO - You can not created a RubyForge project, OR have not run <code>rubyforge config</code>
-yet to refresh your local rubyforge data with this projects' id information.
+h2. To track a package
 
-When you do this, this message will magically disappear!
+<pre>USPS.track("Tracking Number")
+#This will return an array of tracking events example shown below
 
-Or you can hack website/index.txt and make it all go away!!
+[{:eventzipcode=>"33436", :event=>"Arrival at Unit", :eventtime=>"7:23 am", :eventdate=>"June 14, 2008",
+ :eventcity=>"BOYNTON BEACH", :eventstate=>"FL"},
+ {:eventzipcode=>"32862", :event=>"Processed", :eventtime=>"9:50 pm", 
+ :eventdate=>"June 13, 2008", :eventcity=>"ORLANDO",    :eventstate=>"FL"},
+ {:eventzipcode=>"07032", :event=>"Processed", :eventtime=>"1:19 am",
+ :eventdate=>"June 13, 2008", :eventcity=>"KEARNY",     :eventstate=>"NJ"},
+ {:eventzipcode=>"07024", :event=>"Acceptance", :eventtime=>"3:03 pm", :eventdate=>"June 12, 
+ 2008", :eventcity=>"FORT LEE", :eventstate=>"NJ"}]
 
-<% end %>
+#Loop through and display as you wish
+</pre>
 
-* github: "http://github.com/fotoverite/awesome_usps/tree/master":http://github.com/fotoverite/awesome_usps/tree/master
+h2. To get rates for a single or group of packages.
 
-<pre>git clone git://github.com/fotoverite/awesome_usps.git</pre>
+<pre>#There are two APIs. One for domestic, the other for international packages.
+	 
+USPS.domestic_rates(ZIP, Packages, options={})
+USPS.world_rates(Country, Packages, options={})
+
+#Both will return and array containg a hash of rates for each package.
+#To access a rate hash for use you can do 
+
+array = USPS.world_rates(Country, Packages, options={})
+array[0][Priority Mail International
 
+#You can also loop through and sort
+</pre>
 
-TODO - add "github_username: username" to ~/.rubyforge/user-config.yml and newgem will reuse it for future projects.
+h2. Address Verification
 
+<pre>#All methods here will take a location array of up to five address
+	
+#To verify an address and fill in missing information. 
+#If mulitple addresses were found for an address :verified => false
+
+usps.veryify_address("locations array")
+
+#Will fill in missing zip5 and zip4 for an address
+usps.zipcode_lookup("location array")
+
+#Will fill in missing City and State for an address
+usps.city_state_lookup
+</pre>
+
+h2. Service Standards
+
+<pre>usps.priority_mail_estimated_time(origin, destination)
+	
+usps.standard_mail_estimated_time(origin, destination)
+
+#Both of these methods returns a number for the amount of days a package will take to reach 
+#its destination.
+</pre>
+
+h2. Express Mail Commitment
+
+<pre>usps.express_mail_commitment(origin, destination, date=nil)
+	
+#returns a array of hashs containing commitment information. Example shown below
+[{:state=>"MD", :cutoff=>"6:00 PM", :facility=>"EXPRESS MAIL COLLECTION BOX", :zip=>"20770", 
+:street=>"119 CENTER WAY", :city=>"GREENBELT"}, {:state=>"MD", :cutoff=>"3:00 PM", 
+:facility=>"EXPRESS MAIL COLLECTION BOX", :zip=>"20770", :street=>"7500 GREENWAY CENTER DRIVE", 
+:city=>"GREENBELT"}]
+</pre>
+
+h1(smallish). Label APIs
+
+All label API's generate a label image  encoded via 64bit encryption. It must be decrypted by using  
+Base64.decode64(Image_file) to display correctly. The only choices for image_type right now are pdf and TIFF
+An easy way to test and intergrate is to set up something along these lines in a controller.
+
+<pre>
+def deliver_confirmation
+    image = USPS.new("XXXXXX").canned_delivery_confirmation_label_test
+    send_data Base64.decode64(image[:label]), :type => image[:image_type], :disposition => "inline"
+end
+</pre>
+
+All labels except for international labels take a straight name for their XML. 
+When using International label APIs you must include both a first and last name
+
+h2. Delivery and Signature Label Creation
+
+<pre>usps.delivery_confirmation_label(origin, destination, service_type, image_type, label_type=1, options={})
+usps.signature_confirmation_label(origin, destination, service_type, image_type, label_type=1, options={}) 
+
+#label_type can be set to 2 if you desire to create your own labels. No label will be generated for you,
+#you simply will receive a  confirmation label to use with the image you create. 
+
+#Option hash can contain
+
+* :weight_in_ounces 
+* :seperate => puts the label directions on a seperate page. 
+* :po_zip_code => Post Offic zip code
+* :label_date => Can be set up to four days in the future
+* :customer_reference_number
+* :address_service => ill be notified in the future if address has been changed
+* :sender_name, :sender_email, 
+  :recipient_name, :recipient_email  => Used together to send an email to the recipient.
+
+</pre>
+
+h2. Electronic Merchandise Return Label Creation
+
+<pre>usps.merch_return(service_type, customer, retailer, permit_number, 
+                  post_office, postage_delivery_unit,  ounces, image_type, options={})
+#permit_number => Input permit number provided by your local post office.
+#post_office => Location class of post office that issued the permit. Address not needed
+#postage_delivery_unit => Location class for delivery unit you are sending the package to.
+
+#Option hash can contain
+
+ * :confirmation => "Includes delivery confirmation with the label. To enable set to true" 
+ * :insurance_value 
+ * :rma => "Return Materials Authorization Number"
+ * :RMABarcode => "Will Render Barcode on Label if set to true and a RMA has been entered"
+ * :sender_name, :sender_email, 
+   :recipient_name, :recipient_email  => Used together to send an email to the recipient. 
+
+#Output hash contains postnet number and the cost for sending. Under :postnet and :cost respectively.
+</pre>
+
+h2. Express Mail Label Creation
+
+<pre>usps.express_mail_label(orgin, destination, ounces, image_type, options={})
+	
+#Option hash can contain
+
+ * :flat_rate => "Can be set to true if using flat rate envelopes"
+ * :standardize_address => "Verify Address"
+ * :waiver_signature => "No Signature Required for Delivery"
+ * :no_holiday => "Do not deliver on a holiday"
+ * :no_weekend
+ * :seperate => puts the label directions on a seperate page
+ * :po_zip_code
+ * :label_date  => Can be set up to four days in the future
+ * :sender_name, :sender_email, 
+   :recipient_name, :recipient_email  => Used together to send an email to the recipient. 
+
+#Output hash contains postage cost for sending. Can be accessed by :postage
+</pre>
+
+h2. International Mail Labels Creation
+
+<pre>usps.express_mail_international_label(sender, receiver, items, image_type, po_box_flag ="N",
+image_layout="ALLINONEFILE", label_type="1", options={})
+
+usps.priority_mail_international_label(sender, receiver, items, image_type, po_box_flag ="N",
+image_layout="ALLINONEFILE", label_type="1", options={})
+
+usps.first_class_international_label(sender, receiver, items, image_type, po_box_flag ="N",
+image_layout="ALLINONEFILE", label_type="1", options={})
+
+#label_type can be set to 2 if you desire to create your own labels. No label will be generated for you,
+#items => InternationalItem.new can be an array of objects or singular
+#content_type => Options are "MERCHANDISE", "SAMPLE", "GIFT", "DOCUMENTS", "RETURN", "OTHER"
+#If OTHER is selected content type must be described by :other => "Description" in the option hash.
+#image_layout => "Allows for a few options"
+#po_box_flag  can be set to "Y" if items are being sent to a PO-Box
+
+Option Hash for priority and express can contain
+
+ * :middle_initial => "middle initial of sender"
+ * :from_customs_reference
+ * :to_customs_reference
+ * :fax => "fax of receiver"
+ * :email => "email of receiver"
+ * :non_delivery_option => "Return, Reject, Abaddon. Defaults to abaddon."
+ * :alt_return_address1 => "used to explain where package goes 
+    if delivery_option set to . Goes up to alt_return_address6"
+ * :alt_return_country
+ * :container => "VARIABLE or FLATRATEENV"
+ * :insurance_number
+ * :Postage => "If postage is already known. Will be caculated if left blank. "
+ * :other
+ * :comments
+ * :license_number
+ * :certificate_number
+ * :invoice_number
+ * :reference_number
+ * :po_zip_code
+ * :label_date  => Can be set up to four days in the future
+ * :hold => "Hold for manifest"
+Option Hash for first_class can contain
+ * :middle_initial => "middle initial of sender"
+ * :from_customs_reference
+ * :to_customs_reference
+ * :fax => "fax of receiver"
+ * :email => "email of receiver"
+ * :first_class_mail_type
+ * :machinable => "True or False"
+ * :other
+ * :comments
+ * :label_date  => Can be set up to four days in the future
+ * :hold => "Hold for manifest"
+
+#Output hash contains postage cost, total value of all items, SDRValue and the Bar code number.
+#Can be access :postage, :totalvalue, :sdrvalue, and :barcodenumber respectively. 
+</pre>
+
+h2. Open Distribute Priority Label Creation
+
+<pre>#TODO a good description for what Open Distribute Priority actually means
+usps.open_distrubute_priority_label(orgin, destination, 
+     package_weight_in_ounces, mail_type, image_type, label_type=1, options={})
+
+#label_type can be set to 2 if you desire to create your own labels. No label will be generated for you,
+#you simply will receive a  confirmation label to use with the image you create.
+#destination class must contain :facility_type, See API Document for explination of the different types
+#mail_type can be be, "Letters", "Flats", "Parcels", "Mixed" or "Other" 
+#If other is chosen it must be described in the option hash via :other => "Description"
+
+#Option has can contain
+ * :permit_number => "Issued by Post Office"
+ * :permit_zip => "Zip of Post Office that issued permit. Must be included if using :permit_number"
+ * :po_zip_code
+ * :other
+ * :no_weekend
+ * :seperate => puts the label directions on a seperate page
+ * :label_date  => Can be set up to four days in the future
+</pre>
+
+
+h2. Forum
+
+"http://groups.google.com/group/awesome_usps":http://groups.google.com/group/awesome_usps
+
+TODO - create Google Group - awesome_usps
+
+h2. How to submit patches
+
+You can fetch the source from either:
+
+* rubyforge: "http://rubyforge.org/scm/?group_id=6811":http://rubyforge.org/scm/?group_id=6811
+
+<pre>git clone git://rubyforge.org/awesome_usps.git</pre>
+
+or
 
 * gitorious: "git://gitorious.org/awesome_usps/mainline.git":git://gitorious.org/awesome_usps/mainline.git
 
@@ -74,7 +387,6 @@ h3. Build and test instructions
 rake test
 rake install_gem</pre>
 
-
 h2. License
 
 This code is free to use under the terms of the MIT license. 

data/website/stylesheets/screen.css

@@ -1,13 +1,13 @@
 body {
-  background-color: #E1D1F1;
+  background-color: #D8E2F9;
   font-family: "Georgia", sans-serif;
   font-size: 16px;
   line-height: 1.6em;
   padding: 1.6em 0 0 0;
-  color: #333;
+  color: #000;
 }
 h1, h2, h3, h4, h5, h6 {
-  color: #444;
+  color: #43324C;
 }
 h1 { 
   font-family: sans-serif;
@@ -17,6 +17,17 @@ h1 {
   letter-spacing: -0.1ex;
 	margin: 5px;
 }
+
+small {
+
+	color:#0017FF;
+}
+.smallish
+{
+		font-family: serif;
+	font-size:3em;
+	padding:5px 0 5px 0;
+}
 li {
   padding: 0;
   margin: 0;
@@ -24,7 +35,7 @@ li {
 }
 a {
   color: #5E5AFF;
-	background-color: #DAC;
+	background-color: #A5DDD2;
   font-weight: normal;
   text-decoration: underline;
 }
@@ -37,9 +48,12 @@ blockquote {
 .caps {
   font-size: 80%;
 }
+span.caps, h2.caps, h3.caps {
+	font-size:100%;
+}
 
 #main {
-  width: 45em;
+  width: 900px;
   padding: 0;
   margin: 0 auto;
 }
@@ -81,9 +95,11 @@ pre, code {
   font-family: monospace;
   font-size: 90%;
   line-height: 1.4em;
-  color: #ff8;
-  background-color: #111;
+  color: #FFE26B;
+  background-color: #000;
   padding: 2px 10px 2px 10px;
+  border: 1px solid #ECDF2A;
+  padding:15px 5px 15px 10px;	
 }
 .comment { color: #aaa; font-style: italic; }
 .keyword { color: #eff; font-weight: bold; }
@@ -101,12 +117,12 @@ pre, code {
   text-align: right;
   font-family: sans-serif;
   font-weight: normal;
-  background-color: #B3ABFF;
+  background-color: #b3abff;
   color: #141331;
   padding: 15px 20px 10px 20px;
   margin: 0 auto;
 	margin-top: 15px;
-  border: 3px solid #141331;
+  border: 3px solid #F1C129;
 }
 
 #version .numbers {

data/website/template.html.erb

@@ -37,7 +37,7 @@
     </div>
     <%= body %>
     <p class="coda">
-      <a href="FIXME email">FIXME full name</a>, <%= modified.pretty %><br>
+      <a href="FotoVerite@gmail.com">Matthew Bergman</a>, <%= modified.pretty %><br>
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
     </p>
 </div>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: awesome_usps
 version: !ruby/object:Gem::Version 
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors: 
 - Matthew Bergman
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-08-15 00:00:00 -04:00
+date: 2008-08-17 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -77,11 +77,11 @@ files:
 has_rdoc: true
 homepage: http://awesome-usps.rubyforge.org
 post_install_message: |+
+  To use Awesome! USPS in your app use require 'awesome_USPS' in your environment.rb or production.rb
   
   For more information on awesome_usps, see http://awesome_usps.rubyforge.org
   
-  NOTE: Change this information in PostInstall.txt 
-  You can also delete it if you don't want it.
+  
   
   
 rdoc_options: