usps.canned_tracking

#In your environment.rb or production.rb
include FotoVerite

# Then to access the plugin you much create an instance of USPS class
 usps = USPS.new('Your user name')


# Package up a poster and a Wii for your nephew.
# Note the Package Module has been taken directly from Active Shipping. Thank you James MacAulay for developing such great code. 
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
]

#Create a location to use with the Api
 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")

#International Item Class
#Only should be used in conjunction with the Internal Label Api 
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")
]

	#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.

USPS.track("Tracking Number")

#This will return an array of tracking events example shown below

[{: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"}]

#Loop through and display as you wish

#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

#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.verify_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

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. 

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"}]	

#An easy way to test and intergrate is to set up something along these lines in a controller. 

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

#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

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. 

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. 

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

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. 

<Postage>96.25</Postage>
            <TotalValue>16.65</TotalValue>
            <SDRValue>11.42</SDRValue>
            <BarcodeNumber>LJ000100644US</BarcodeNumber>

#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