usps 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Chris Gaffney
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,56 @@
+= usps
+
+Ruby API for accessing the USPS WebTools API found here: http://www.usps.com/webtools/technical.htm
+
+Usage of this library assumes you already have a USPS API account and that all priviledges have been granted.
+
+== 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
+
+   <DeliveryConfirmationV3.0Request>    -- USPS::Request::DeliveryConfirmation        (for production)
+   <DeliveryConfirmCertifyV3.0Request>  -- USPS::Request::DeliveryConfirmationCertify (for testing)
+
+== How to use?
+
+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:
+
+  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 a simple
+  
+  USPS_USER="[username]" rake certify
+
+If any of the tests fail, you don't have access to that API and may need to work with USPS to fix.
+
+== 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.
+
+
+== Copyright
+
+Copyright (c) 2010 Chris Gaffney. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |gem|
+    gem.name = "usps"
+    gem.summary = "USPS Webtools API for Ruby"
+    gem.description = "USPS Webtools API for Ruby."
+    gem.email = "gaffneyc@gmail.com"
+    gem.homepage = "http://github.com/gaffneyc/usps"
+    gem.authors = ["Chris Gaffney"]
+
+    gem.add_dependency 'builder',  '>= 2.1.2'
+    gem.add_dependency 'nokogiri', '>= 1.4.1'
+    gem.add_dependency 'typhoeus', '>= 0.1.18'
+
+    gem.add_development_dependency "mocha", ">= 0.9.8"
+    gem.add_development_dependency "rspec", ">= 1.3.0"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "usps #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+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 -rusps lib/usps/test.rb"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/usps.rb

@@ -0,0 +1,45 @@
+require 'builder'
+require 'nokogiri'
+
+module USPS
+  require 'usps/errors'
+  require 'usps/configuration'
+
+  autoload :Client,   'usps/client'
+  autoload :Address,  'usps/address'
+  autoload :Request,  'usps/request'
+  autoload :Response, 'usps/response'
+
+  class << self
+    attr_writer :config
+
+    def client
+      @client ||= Client.new
+    end
+
+    def testing=(val)
+      config.testing = val
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure(&block)
+      block.call(self.config)
+    end
+
+    # These two methods are currently here for backwards compatability
+    def username=(user)
+      config.username = user
+    end
+
+    def username
+      config.username
+    end
+
+    def get_city_and_state_for_zip(zip)
+      USPS::Request::CityAndStateLookup.new(zip).send!.get(zip)
+    end
+  end
+end

data/lib/usps/address.rb

@@ -0,0 +1,72 @@
+# TODO: Documentation
+#
+# The USPS API uses a standard where Address2 is the street adress and Address1 is
+# 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)
+
+  # Alias address getters and setters for a slightly more expressive api
+  alias :address  :address1
+  alias :address= :address1=
+  alias :extra_address  :address2
+  alias :extra_address= :address2=
+
+  # The USPS always refers to company as firm
+  alias :firm :company
+  alias :firm= :company=
+
+  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 zip
+    zip4 ? "#{zip5}-#{zip4}" : zip5.to_s
+  end
+
+  # Sets zip5 and zip4 if given a zip code in the format "99881" or "99881-1234"
+  def zip=(val)
+    self.zip5, self.zip4 = val.to_s.split('-')
+  end
+
+  # Check with the USPS if this address can be verified and will in missing
+  # fields (such as zip code) if they are available.
+  def valid?
+    @error = nil
+    standardize
+    true
+  rescue USPS::Error => e
+    @error = e
+    false
+  end
+
+  def standardize
+    response = USPS::Request::AddressStandardization.new(self).send!
+    response[self]
+  end
+
+  def standardize!
+    replace(self.standardize)
+  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/client.rb

@@ -0,0 +1,56 @@
+require 'typhoeus'
+
+module USPS
+  class Client
+    def request(request, &block)
+      server = server(request)
+
+      # The USPS documentation shows all requests as being GET requests, but
+      # the servers also appear to support POST. We're using POST here so we
+      # don't need to escape the request and to keep from running into any
+      # concerns with data length.
+      response = Typhoeus::Request.post(server, {
+        :timeout => USPS.config.timeout,
+        :params => {
+          "API" => request.api,
+          "XML" => request.build
+        }
+      })
+
+      # Parse the request
+      xml = Nokogiri::XML.parse(response.body)
+
+      # Process and raise errors
+      if((error = xml.search('Error')).any?)
+        # This is where things get a little tricky. There are a bunch of errors
+        # that the USPS can send back.
+        why = error.search('Description').text
+        code = error.search('Number').text
+        source = error.search('Source').text
+
+        raise Error.for_code(code).new(why, code, source)
+      end
+
+      # Initialize the proper response object and parse the message
+      request.response_for(xml)
+    end
+
+    def testing?
+      USPS.config.testing
+    end
+
+    private
+    def server(request)
+      dll = testing? ? "ShippingAPITest.dll" : "ShippingAPI.dll"
+
+      case
+      when request.secure?
+        "https://secure.shippingapis.com/#{dll}"
+      when testing?
+        "http://testing.shippingapis.com/#{dll}"
+      else
+        "http://production.shippingapis.com/#{dll}"
+      end
+    end
+  end
+end

data/lib/usps/configuration.rb

@@ -0,0 +1,16 @@
+module USPS
+  # Configuration options:
+  #   username: Provided by the USPS during registration
+  #   timeout: Connection timeout in milliseconds, nil to disable
+  #   testing: Should requests be done against the testing service or not
+  #            (only specific requests are supported).
+  class Configuration < Struct.new(:username, :timeout, :testing)
+    def initialize
+      self.timeout  = 5000
+      self.testing  = false
+      self.username = ENV['USPS_USER']
+    end
+
+    alias :testing? :testing
+  end
+end

data/lib/usps/errors.rb

@@ -0,0 +1,46 @@
+module USPS
+  # Error Hierarchy
+  #
+  # StandardError
+  #   USPS::Error
+  #     USPS::AuthorizationError
+  #     USPS::ValidationError
+  #       USPS::InvalidCityError
+  #       USPS::InvalidStateError
+  #       USPS::AddressNotFoundError
+  #       USPS::MultipleAddressError
+  #       USPS::InvalidImageTypeError
+  class Error < StandardError
+    attr_reader :number, :source
+
+    def initialize(message, number, source)
+      super(message)
+
+      @number = number
+      @source = source
+    end
+
+    class << self
+      def for_code(code)
+        case code
+        when '80040b1a'   ; AuthorizationError
+        when '-2147219400'; InvalidCityError
+        when '-2147219401'; AddressNotFoundError
+        when '-2147219402'; InvalidStateError
+        when '-2147219403'; MultipleAddressError
+        when '-2147218900'; InvalidImageTypeError
+        else              ; Error
+        end
+      end
+    end
+  end
+
+  class AuthorizationError < Error; end
+
+  class ValidationError < Error; end
+  class InvalidCityError < ValidationError; end
+  class InvalidStateError < ValidationError; end
+  class AddressNotFoundError < ValidationError; end
+  class MultipleAddressError < ValidationError; end
+  class InvalidImageTypeError < ValidationError; end
+end

data/lib/usps/request.rb

@@ -0,0 +1,13 @@
+module USPS::Request
+  autoload :Base, 'usps/request/base'
+  autoload :ZipCodeLookup, 'usps/request/zip_code_lookup'
+  autoload :CityAndStateLookup,     'usps/request/city_and_state_lookup'
+  autoload :AddressStandardization, 'usps/request/address_standardization'
+
+  # Delivery and Signature confirmation.
+  # DeliveryConfirmationCertify and SignatureConfirmationCertify should be used for testing
+  autoload :DeliveryConfirmation, 'usps/request/delivery_confirmation'
+  autoload :DeliveryConfirmationCertify, 'usps/request/delivery_confirmation_certify'
+
+  autoload :TrackingLookup, 'usps/request/tracking_lookup'
+end

data/lib/usps/request/address_standardization.rb

@@ -0,0 +1,44 @@
+module USPS::Request
+  # TODO: #send! could be made smarter to send lookup batches
+  class AddressStandardization < Base
+    config(
+      :api => 'Verify',
+      :tag => 'AddressValidateRequest',
+      :secure => false,
+      :response => USPS::Response::AddressStandardization
+    )
+
+    # At most 5 addresses can be verified
+    def initialize(*addresses)
+      @addresses = addresses.flatten
+
+      if @addresses.size > 5
+        raise ArgumentError, 'at most 5 addresses can be verified at a time'
+      end
+    end
+
+    def response_for(xml)
+      self.class.response.new(@addresses, xml)
+    end
+
+    def build
+      super do |builder|
+        @addresses.each_with_index do |addy, i|
+          builder.tag!('Address', :ID => i) do
+            builder.tag!('FirmName', addy.firm)
+
+            # Address fields are swapped in the USPS API
+            builder.tag!('Address1', addy.extra_address)
+            builder.tag!('Address2', addy.address)
+
+            builder.tag!('City', addy.city)
+            builder.tag!('State', addy.state)
+
+            builder.tag!('Zip5', addy.zip5)
+            builder.tag!('Zip4', addy.zip4)
+          end
+        end
+      end
+    end
+  end
+end