usps-fork 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 889fe783648fc3fec6339e83589c3a2082142798
+  data.tar.gz: a7f2607ab4f25de1e616ff259d07d159e33887d4
+SHA512:
+  metadata.gz: 0ec28c0dae08024f7df5116f411a1ac11c6221a5f31c4457ee736060cc410fa9bfcee80fcee9f9acd7ff6db8da0b4aa9f6304fe134ff2f3d76311c3f7c3a4c54
+  data.tar.gz: 695cfb8dff0db59bb3a63fa3e5efe99723fc191e0a4fcb11d8516ef571dec820e42d665f22a9102236426e24f2675c132f5f350b0ec45fd1f2e0334a3db265ff

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

@@ -0,0 +1,89 @@
+# 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
+```
+
+## Further Reading
+
+- [USPS API docs](https://www.usps.com/business/web-tools-apis/welcome.htm)
+- [18F's USPS API Notes](https://github.com/18F/usps-api-notes)
+
+## Copyright
+
+Copyright (c) 2014 Chris Gaffney. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,15 @@
+require 'bundler/setup'
+Bundler::GemHelper.install_tasks
+
+require 'rake'
+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

@@ -0,0 +1,47 @@
+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 :VERSION,       'usps/version'
+  autoload :Response,      'usps/response'
+  autoload :TrackDetail,   'usps/track_detail'
+
+  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, :return_text)
+
+  # 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,55 @@
+require 'typhoeus'
+
+module USPS
+  class Client
+    def request(request, &block)
+      server = server(request)
+
+      # Make the API request to the USPS servers. Used to support POST, now it's
+      # just GET request *grumble*.
+      options = { timeout: USPS.config.timeout, 
+                  params: { "API" => request.api, "XML" => request.build } }
+
+      unless USPS.config.proxy.blank?
+        options.merge!({ proxy: USPS.config.proxy })
+      end
+      
+      response = Typhoeus::Request.get(server, options)
+
+      # 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,17 @@
+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, :proxy)
+    def initialize
+      self.timeout  = 5
+      self.testing  = false
+      self.username = ENV['USPS_USER']
+      self.proxy = nil
+    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,14 @@
+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'
+  autoload :TrackingFieldLookup, 'usps/request/tracking_field_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

data/lib/usps/request/base.rb

@@ -0,0 +1,42 @@
+module USPS::Request
+  class Base
+    class << self
+      attr_reader :api, :tag, :secure, :response
+
+      alias :secure? :secure
+
+      # Config given
+      #   api: The USPS API name as given in the request URL
+      #   tag: The root tag used for the request
+      #   secure: Whether or not the request is against the secure server
+      #   response: The USPS::Response class used to handle responses
+      def config(options = {})
+        @api = options[:api].to_s
+        @tag = options[:tag].to_s
+        @secure = !!options[:secure]
+        @response = options[:response]
+      end
+    end
+
+    def send!
+      USPS.client.request(self)
+    end
+
+    def secure?
+      !!self.class.secure?
+    end
+
+    def api
+      self.class.api
+    end
+
+    def response_for(xml)
+      self.class.response.parse(xml)
+    end
+
+    def build(&block)
+      builder = Builder::XmlMarkup.new(:indent => 0)
+      builder.tag!(self.class.tag, :USERID => USPS.config.username, &block)
+    end
+  end
+end