usps 0.1.2 → 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 32013f6daa8af9cd35517d0b37b200bf9db91974
+  data.tar.gz: d9309024e63911cf3cb3d3b150160e77963f4ee3
+SHA512:
+  metadata.gz: 391f24ffa46925ac60facbfa9ee5ab1add219781d35c216b093257c12866ffc329f59f2ca8d89165567bbae8a051f57be706329366c3d7e84d3edfb28dee21d6
+  data.tar.gz: c1f48611b6b72cd797266ddb77efba8d5a7736fdedfeaebc4a3d839e63c543720cdedfa9c5f2e93be35d436c02c02c626ab41cd4652bc60c288ede67098a6992

data/README.md

@@ -0,0 +1,84 @@
+# usps
+
+[![Build Status](https://travis-ci.org/gaffneyc/usps.svg?branch=master)](https://travis-ci.org/gaffneyc/usps)
+
+Ruby API for accessing the USPS WebTools API found here: https://www.usps.com/business/webtools.htm
+
+PDF Guides can be found here: https://www.usps.com/business/webtools-technical-guides.htm
+
+Usage of this library assumes you already have a USPS API account and that all priviledges have been granted.
+
+## Project Status - Looking for a Maintainer
+
+This code is no longer properly maintained as I'm no longer with the company it was developed for.
+If you're using it and would be interested in maintaining it please send me a message and I can
+get you set up.
+
+## Exposed API Calls
+
+The following USPS API calls are currently exposed through this library:
+
+```
+<AddressValidateRequest>             -- USPS::Request::AddressStandardization
+<CityStateLookupRequest>             -- USPS::Request::CityAndStateLookup
+<ZipCodeLookupRequest>               -- USPS::Request::ZipCodeLookup
+<TrackRequest>                       -- USPS::Request::TrackingLookup
+<TrackFieldRequest>                  -- USPS::Request::TrackingFieldLookup
+
+<DeliveryConfirmationV3.0Request>    -- USPS::Request::DeliveryConfirmation        (for production)
+<DeliveryConfirmCertifyV3.0Request>  -- USPS::Request::DeliveryConfirmationCertify (for testing)
+```
+
+## Usage
+
+Using the library is as simple as building a new USPS::Request::[type] object, calling #send! and using the response.
+For example, to send a tracking request you'd do the following:
+
+```ruby
+request = USPS::Request::TrackingLookup.new(tracking_number)
+response = request.send!
+
+response.summary
+response.details
+```
+
+The library assumes that either ENV['USPS_USER'] is set, or that you set USPS.username to your USPS API username.
+
+See the individual USPS::Request classes for details on how to use them.
+
+## USPS API Certification
+
+Part of the process of setting up an account with the USPS API is to run certain tests against the USPS API.
+This library has all the requisite tests built in, runnable with rake:
+
+```  
+$ USPS_USER="[username]" rake certify
+```
+
+or as an installed gem:
+
+```
+$ USPS_USER="[username]" ruby -rubygems -e "require 'usps/test'"
+```
+
+If any of the tests fail, you don't have access to that API and may need to work with USPS to fix it.
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Testing
+
+```
+$ rspec
+```
+
+## Copyright
+
+Copyright (c) 2014 Chris Gaffney. See LICENSE for details.

data/Rakefile

@@ -2,16 +2,14 @@ require 'bundler/setup'
 Bundler::GemHelper.install_tasks
 
 require 'rake'
-require 'spec/rake/spectask'
-
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.spec_files = FileList['spec/**/*_spec.rb']
-end
-
-task :default => :spec
+require 'rspec/core/rake_task'
 
 desc "Run the certification tests against USPS's API. Requires ENV['USPS_USER'] to be set or passed in."
 task :certify do
   ruby "-rubygems -Ilib lib/usps/test.rb"
 end
+
+desc "Run RSpec tests"
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/lib/usps.rb

@@ -5,11 +5,12 @@ module USPS
   require 'usps/errors'
   require 'usps/configuration'
 
-  autoload :Client,   'usps/client'
-  autoload :Address,  'usps/address'
-  autoload :Request,  'usps/request'
-  autoload :VERSION,  'usps/version'
-  autoload :Response, 'usps/response'
+  autoload :Client,        'usps/client'
+  autoload :Address,       'usps/address'
+  autoload :Request,       'usps/request'
+  autoload :VERSION,       'usps/version'
+  autoload :Response,      'usps/response'
+  autoload :TrackDetail,   'usps/track_detail'
 
   class << self
     attr_writer :config

data/lib/usps/address.rb

@@ -4,7 +4,7 @@
 # the apartment, suite, etc... I have switched them to match how I see them on an envelope.
 # Additionally they are refered to address and extra_address though both address1 and address2
 # work. Just remember they are flip flopped based on the USPS documentation.
-class USPS::Address < Struct.new(:name, :company, :address1, :address2, :city, :state, :zip5, :zip4)
+class USPS::Address < Struct.new(:name, :company, :address1, :address2, :city, :state, :zip5, :zip4, :return_text)
 
   # Alias address getters and setters for a slightly more expressive api
   alias :address  :address1

data/lib/usps/configuration.rb

@@ -6,7 +6,7 @@ module USPS
   #            (only specific requests are supported).
   class Configuration < Struct.new(:username, :timeout, :testing)
     def initialize
-      self.timeout  = 5000
+      self.timeout  = 5
       self.testing  = false
       self.username = ENV['USPS_USER']
     end

data/lib/usps/request.rb

@@ -9,5 +9,6 @@ module USPS::Request
   autoload :DeliveryConfirmation, 'usps/request/delivery_confirmation'
   autoload :DeliveryConfirmationCertify, 'usps/request/delivery_confirmation_certify'
 
-  autoload :TrackingLookup, 'usps/request/tracking_lookup'
+  autoload :TrackingLookup,      'usps/request/tracking_lookup'
+  autoload :TrackingFieldLookup, 'usps/request/tracking_field_lookup'
 end

data/lib/usps/request/tracking_field_lookup.rb

@@ -0,0 +1,28 @@
+module USPS::Request
+  # Given a valid USPS tracking number, use this class to request
+  # tracking information from USPS's systems.
+  #
+  # Returns a USPS::Response::TrackingFieldLookup object with the pertinent
+  # information
+  class TrackingFieldLookup < Base
+    config(
+      :api => 'TrackV2',
+      :tag => 'TrackFieldRequest',
+      :secure => false,
+      :response => USPS::Response::TrackingFieldLookup
+    )
+
+    # Build a new TrackingLookup request.
+    # Takes the USPS tracking number to request information for
+    def initialize(track_id)
+      @track_id = track_id
+    end
+
+    def build
+      super do |builder|
+        builder.tag!('TrackID', :ID => @track_id)
+      end
+    end
+
+  end
+end

data/lib/usps/response.rb

@@ -4,4 +4,5 @@ module USPS::Response
   autoload :DeliveryConfirmation,   'usps/response/delivery_confirmation'
   autoload :AddressStandardization, 'usps/response/address_standardization'
   autoload :TrackingLookup,         'usps/response/tracking_lookup'
+  autoload :TrackingFieldLookup,    'usps/response/tracking_field_lookup'
 end

data/lib/usps/response/address_standardization.rb

@@ -21,6 +21,19 @@ module USPS::Response
       @addresses[address]
     end
     alias :[] :get
+    
+    def addresses
+      @addresses
+    end
+    
+    def to_h
+      hash = {}
+      @addresses.each_pair do |key, value|
+        hash[key.to_h] = value.to_h
+      end
+      
+      hash
+    end
 
     private
     def parse(node)
@@ -31,7 +44,8 @@ module USPS::Response
         :city => node.search('City').text,
         :state => node.search('State').text,
         :zip5 => node.search('Zip5').text,
-        :zip4 => node.search('Zip4').text
+        :zip4 => node.search('Zip4').text,
+        :return_text => node.search('ReturnText').text,
       )
     end
   end

data/lib/usps/response/city_and_state_lookup.rb

@@ -17,12 +17,26 @@ module USPS::Response
       end
     end
 
-    # Returns an address representing the standardized version of the given
-    # address from the results of the query.
+    # Returns a single city/state pair given a zip5
     def get(zip)
       @data[zip.to_i]
     end
     alias :[] :get
+    
+    # Returns all city/state data from the query results
+    def data
+      @data
+    end
+    
+    # Returns all city/state data as a pure Ruby hash (e.g. no Structs as values)
+    def to_h
+      hash = {}
+      @data.each_pair do |key, value|
+        hash[key] = value.to_h
+      end
+      
+      hash      
+    end
   end
 end
 

data/lib/usps/response/tracking_field_lookup.rb

@@ -0,0 +1,34 @@
+module USPS::Response
+  # Response object from a USPS::Request::TrackingLookup request. 
+  # Includes a summary of the current status of the shipment, along with
+  # an array of details of the shipment's progress
+  class TrackingFieldLookup < Base
+
+    attr_accessor :summary, :details
+
+
+    def initialize(xml)
+       @summary = parse(xml.search("TrackSummary"))
+       @details = []
+       xml.search("TrackDetail").each do |detail|
+         @details << parse(detail)
+       end
+     end
+     
+     private
+     def parse(node)
+       USPS::TrackDetail.new(
+         :event_time => node.search('EventTime').text,
+         :event_date => node.search('EventDate').text,
+         :event => node.search('Event').text,
+         :event_city => node.search('EventCity').text,
+         :event_state => node.search('EventState').text,
+         :event_zip_code => node.search('EventZIPCode').text,
+         :event_country => node.search('EventCountry').text,
+         :firm_name => node.search('FirmName').text,
+         :name => node.search('Name').text,
+         :authorized_agent => node.search('AuthorizedAgent').text
+       )
+     end
+  end
+end

data/lib/usps/response/tracking_lookup.rb

@@ -14,6 +14,6 @@ module USPS::Response
         @details << detail.text
       end
     end
-
+ 
   end
 end

data/lib/usps/track_detail.rb

@@ -0,0 +1,49 @@
+require 'time'
+# TODO: Documentation
+#
+class USPS::TrackDetail < Struct.new(:event_time, :event_date, :event, :event_city, :event_state, :event_zip_code, :event_country, :firm_name, :name, :authorized_agent)
+
+  # Alias address getters and setters for a slightly more expressive api
+  alias :city  :event_city
+  alias :city= :event_city=
+  alias :state :event_state
+  alias :state= :event_state=
+  alias :zip_code :event_zip_code
+  alias :zip_code= :event_zip_code=
+  alias :country :event_country
+  alias :country= :event_country=
+
+  attr_reader :error
+
+  def initialize(options = {}, &block)
+    options.each_pair do |k, v|
+      self.send("#{k}=", v)
+    end
+
+    block.call(self) if block
+  end
+  
+  def date
+    time = "#{event_date} #{event_time}".strip
+    begin
+      Time.parse(time) unless time.empty?
+    rescue ArgumentError
+      return nil
+    end
+  end
+
+  # Similar to Hash#replace, overwrite the values of this object with the other.
+  # It will not replace a provided key on the original object that does not exist
+  # on the replacing object (such as name with verification requests).
+  def replace(other)
+    raise ArgumentError unless other.is_a?(USPS::Address)
+
+    other.each_pair do |key, val|
+      # Do not overwrite values that may exist on the original but not on
+      # the replacement.
+      self[key] = val unless val.nil?
+    end
+
+    self
+  end
+end

data/lib/usps/version.rb

@@ -1,3 +1,3 @@
 module USPS
-  VERSION = '0.1.2'
+  VERSION = '0.1.3'
 end

data/spec/address_spec.rb

@@ -4,7 +4,7 @@ describe USPS::Address do
   it "should have the expected fields" do
     address = USPS::Address.new
 
-    address.should respond_to(
+    expect(address).to respond_to(
       :name, :name=,
       :address1, :address1=,
       :address2, :address2=,
@@ -22,21 +22,21 @@ describe USPS::Address do
       :city => 'Holland'
     )
 
-    address.name.should == 'Chris'
-    address.address.should == '123 Main St'
-    address.city.should == 'Holland'
+    expect(address.name).to eq('Chris')
+    expect(address.address).to eq('123 Main St')
+    expect(address.city).to eq('Holland')
   end
 
   it "know how to combine the zip coes" do
-    USPS::Address.new(:zip5 => 12345).zip.should == '12345'
-    USPS::Address.new(:zip5 => 12345, :zip4 => 9999).zip.should == '12345-9999'
+    expect(USPS::Address.new(:zip5 => 12345).zip).to eq('12345')
+    expect(USPS::Address.new(:zip5 => 12345, :zip4 => 9999).zip).to eq('12345-9999')
   end
 
   it "should be able to parse zip into individual parts" do
     addy = USPS::Address.new(:zip => '12345-9988')
-    addy.zip5.should == '12345'
-    addy.zip4.should == '9988'
-    addy.zip.should  == '12345-9988'
+    expect(addy.zip5).to eq('12345')
+    expect(addy.zip4).to eq('9988')
+    expect(addy.zip).to  eq('12345-9988')
   end
 
   it "should be able to be verified with the USPS" do
@@ -48,18 +48,18 @@ describe USPS::Address do
       :zip => 20006
     )
 
-    USPS.client.should_receive(:request).and_return(
+    expect(USPS.client).to receive(:request).and_return(
       USPS::Response::AddressStandardization.new(
         addy, load_xml('address_standardization_1.xml')
       )
     )
 
-    addy.valid?.should be_true
+    expect(addy.valid?).to be_truthy
 
     error = USPS::Error.new('error', '1234', 'source')
     # Failure
-    USPS.client.should_receive(:request).and_raise(error)
-    addy.valid?.should be_false
-    addy.error.should be(error)
+    expect(USPS.client).to receive(:request).and_raise(error)
+    expect(addy.valid?).to be_falsey
+    expect(addy.error).to be(error)
   end
 end

data/spec/configuration_spec.rb

@@ -7,13 +7,13 @@ describe USPS::Configuration do
   end
 
   it "should have some sensible defaults" do
-    @config.username.should be_nil
-    @config.timeout.should == 5000
-    @config.testing.should be_false
+    expect(@config.username).to be_nil
+    expect(@config.timeout).to eq(5)
+    expect(@config.testing).to be_falsey
   end
 
   it "should grab the username from the environment if available" do
     ENV['USPS_USER'] = 'malcom77'
-    USPS::Configuration.new.username.should == 'malcom77'
+    expect(USPS::Configuration.new.username).to eq('malcom77')
   end
 end

data/spec/data/tracking_field_lookup.xml

@@ -0,0 +1,41 @@
+<?xml version="1.0"?>
+<TrackResponse>
+  <TrackInfo ID="01805213907042762274">
+    <TrackSummary>
+      <EventTime>12:12 pm</EventTime>
+      <EventDate>May 21, 2001</EventDate>
+      <Event>DELIVERED</Event>
+      <EventCity>NEWTON</EventCity>
+      <EventState>IA</EventState>
+      <EventZIPCode>50208</EventZIPCode>
+      <EventCountry/>
+      <FirmName></FirmName>
+      <Name></Name>
+      <AuthorizedAgent></AuthorizedAgent>
+    </TrackSummary>
+    <TrackDetail>
+      <EventTime>9:24 pm</EventTime>
+      <EventDate>March 28, 2001</EventDate>
+      <Event>ENROUTE</Event>
+      <EventCity>DES MOINES</EventCity>
+      <EventState>IA</EventState>
+      <EventZIPCode>50395</EventZIPCode>
+      <EventCountry/>
+      <FirmName/>
+      <Name/>
+      <AuthorizedAgent/>
+    </TrackDetail>
+    <TrackDetail>
+      <EventTime>10:00 pm</EventTime>
+      <EventDate>March 27, 2001</EventDate>
+      <Event>ACCEPTANCE</Event>
+      <EventCity>BLAINE</EventCity>
+      <EventState>WA</EventState>
+      <EventZIPCode>98231</EventZIPCode>
+      <EventCountry/>
+      <FirmName/>
+      <Name/>
+      <AuthorizedAgent/>
+    </TrackDetail>
+  </TrackInfo>
+</TrackResponse>