usps 0.1.0

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

data/lib/usps/request/city_and_state_lookup.rb

@@ -0,0 +1,32 @@
+module USPS::Request
+  # All the address information APIs are essentially identical
+  class CityAndStateLookup < Base
+    config(
+      :api => 'CityStateLookup',
+      :tag => 'CityStateLookupRequest',
+      :secure => false,
+      :response => USPS::Response::CityAndStateLookup
+    )
+
+    # Given a list of zip codes, looks up what city and state they are associated with.
+    #
+    # The USPS api is only capable of handling at most 5 zip codes per request.
+    def initialize(*zip_codes)
+      @zip_codes = zip_codes.flatten
+
+      if(@zip_codes.size > 5)
+        raise ArgumentError, 'at most 5 lookups can be performed per request'
+      end
+    end
+
+    def build
+      super do |builder|
+        @zip_codes.each_with_index do |zip, i|
+          builder.tag!('ZipCode', :ID => i) do
+            builder.tag!('Zip5', zip)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/usps/request/delivery_confirmation.rb

@@ -0,0 +1,88 @@
+module USPS::Request
+  class DeliveryConfirmation < Base
+    config(
+      :api => 'DeliveryConfirmationV3',
+      :tag => 'DeliveryConfirmationV3.0Request',
+      :secure => true,
+      :response => USPS::Response::DeliveryConfirmation
+    )
+
+    attr_reader :to, :from, :weight, :options, :format
+
+    DEFAULTS = {
+      :type    => 1,
+      :format  => 'TIF',
+      :service => 'Priority'
+    }.freeze
+
+    # List of valid options and their mapping to their tag
+    OPTIONS = {
+      :type               => 'Option',
+      :service            => 'ServiceType',
+      :po_zip_code        => 'PoZipCode',
+      :label_date         => 'LabelDate',
+      :customer_reference => 'CustomerRefNo',
+      :separate_receipt   => 'SeparateReceiptPage',
+      :address_service    => 'AddressServiceRequested',
+      :sender_name        => 'SenderName',
+      :sender_email       => 'SenderEMail',
+      :recipient_name     => 'RecipientName',
+      :recipient_email    => 'RecipientEMail'
+    }.freeze
+
+    FORMATS = %w(TIF PDF).freeze
+
+    # === Options:
+    # * <tt>:
+    def initialize(to, from, weight, options = {})
+      @to = to
+      @from = from
+      @weight = weight
+      @options = DEFAULTS.merge(options)
+
+      @type = @options.delete(:type)
+      self.format = @options.delete(:format)
+    end
+
+    def format=(format)
+      format = format.upcase
+
+      unless(FORMATS.include?(format))
+        raise ArgumentError, "Format must be one of #{FORMATS.join(',')}"
+      end
+
+      @format = format.upcase
+    end
+
+    def build
+      super do |builder|
+        builder.tag!('Option', @type)
+        builder.tag!('ImageParameters')
+
+        [
+          [self.from, 'From'],
+          [self.to,   'To']
+        ].each do |address, prefix|
+          builder.tag!("#{prefix}Name",  address.name)
+          builder.tag!("#{prefix}Firm",  address.company)
+          builder.tag!("#{prefix}Address1", address.extra_address)
+          builder.tag!("#{prefix}Address2", address.address)
+          builder.tag!("#{prefix}City",  address.city)
+          builder.tag!("#{prefix}State", address.state)
+          builder.tag!("#{prefix}Zip5",  address.zip5)
+          builder.tag!("#{prefix}Zip4",  address.zip4)
+        end
+
+        builder.tag!('WeightInOunces', self.weight)
+
+        @options.each_pair do |k,v|
+          OPTIONS[k].tap do |tag|
+            builder.tag!(tag, v.to_s) if tag
+          end
+        end
+
+        builder.tag!('ImageType', @format)
+      end
+    end
+  end
+end

data/lib/usps/request/delivery_confirmation_certify.rb

@@ -0,0 +1,10 @@
+module USPS::Request
+  class DeliveryConfirmationCertify < USPS::Request::DeliveryConfirmation
+    config(
+      :api => 'DelivConfirmCertifyV3',
+      :tag => 'DelivConfirmCertifyV3.0Request',
+      :secure => true,
+      :response => USPS::Response::DeliveryConfirmation
+    )
+  end
+end

data/lib/usps/request/tracking_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::TrackingLookup object with the pertinent
+  # information
+  class TrackingLookup < Base
+    config(
+      :api => 'TrackV2',
+      :tag => 'TrackRequest',
+      :secure => false,
+      :response => USPS::Response::TrackingLookup
+    )
+
+    # 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/request/zip_code_lookup.rb

@@ -0,0 +1,45 @@
+module USPS::Request
+  # This class is essentially identical to AddressStandardization but do to how
+  # #build inheritance is being done it's easier just to reimplement it for now.
+  #
+  # TODO: #send! could be made smarter to send lookup batches
+  class ZipCodeLookup < Base
+    config(
+      :api => 'ZipCodeLookup',
+      :tag => 'ZipCodeLookupRequest',
+      :secure => false,
+      :response => USPS::Response::AddressStandardization
+    )
+
+    # At most 5 zip codes can be retrieved at once
+    def initialize(*addresses)
+      @addresses = addresses
+
+      if @addresses.size > 5
+        raise ArgumentError, 'at most 5 lookups can be performed per request'
+      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 1 and 2 are backwards compared to how they appear on an
+            # envelope.
+            builder.tag!('Address1', addy.extra_address)
+            builder.tag!('Address2', addy.address)
+
+            builder.tag!('City', addy.city)
+            builder.tag!('State', addy.state)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/usps/response.rb

@@ -0,0 +1,7 @@
+module USPS::Response
+  autoload :Base, 'usps/response/base'
+  autoload :CityAndStateLookup,     'usps/response/city_and_state_lookup'
+  autoload :DeliveryConfirmation,   'usps/response/delivery_confirmation'
+  autoload :AddressStandardization, 'usps/response/address_standardization'
+  autoload :TrackingLookup,         'usps/response/tracking_lookup'
+end

data/lib/usps/response/address_standardization.rb

@@ -0,0 +1,38 @@
+# TODO: AddressStandardization _can_ handle up to 5 addresses at once and each
+#       can be valid or error out. Currently the system raises an exception if any
+#       are invalid. The error should be by address.
+module USPS::Response
+  class AddressStandardization < Base
+    def initialize(addresses, xml)
+      @addresses = {}
+
+      [addresses].flatten.each_with_index do |addy, i|
+        @addresses[addy] = parse(xml.search("Address[@ID='#{i}']"))
+
+        # Name is not sent nor received so lets make sure to set it so the
+        # standardized version is roughly equivalent
+        @addresses[addy].name = addy.name
+      end
+    end
+
+    # Returns an address representing the standardized version of the given
+    # address from the results of the query.
+    def get(address)
+      @addresses[address]
+    end
+    alias :[] :get
+
+    private
+    def parse(node)
+      USPS::Address.new(
+        :company => node.search('FirmName').text,
+        :address1 => node.search('Address2').text,
+        :address2 => node.search('Address1').text,
+        :city => node.search('City').text,
+        :state => node.search('State').text,
+        :zip5 => node.search('Zip5').text,
+        :zip4 => node.search('Zip4').text
+      )
+    end
+  end
+end

data/lib/usps/response/base.rb

@@ -0,0 +1,13 @@
+module USPS::Response
+  class Base
+    attr_accessor :raw
+
+    class << self
+      def parse(xml)
+        response = self.new(xml)
+        response.raw = xml
+        response
+      end
+    end
+  end
+end

data/lib/usps/response/city_and_state_lookup.rb

@@ -0,0 +1,28 @@
+module USPS::Response
+  class CityAndStateLookup < Base
+    # Result record for a city and state lookup.
+    class Result < Struct.new(:zip, :city, :state); end
+
+    def initialize(xml)
+      @data = {}
+
+      xml.search('ZipCode').each do |node|
+        zip = node.search('Zip5').text.to_i
+
+        @data[zip] = Result.new(
+          zip,
+          node.search('City').text,
+          node.search('State').text
+        )
+      end
+    end
+
+    # Returns an address representing the standardized version of the given
+    # address from the results of the query.
+    def get(zip)
+      @data[zip.to_i]
+    end
+    alias :[] :get
+  end
+end
+

data/lib/usps/response/delivery_confirmation.rb

@@ -0,0 +1,25 @@
+module USPS::Response
+  class DeliveryConfirmation < Base
+    attr_reader :label, :confirmation, :address, :postnet
+
+    alias :confirmation_number :confirmation
+
+    def initialize(xml)
+      # Label is Base64 encoded
+      @label = xml.search('DeliveryConfirmationLabel').text.unpack("m*")[0]
+      @confirmation = xml.search('DeliveryConfirmationNumber').text
+      @postnet = xml.search('Postnet').text
+
+      @address = USPS::Address.new(
+        :name     => xml.search('ToName').text,
+        :company  => xml.search('ToFirm').text,
+        :address  => xml.search('ToAddress2').text,
+        :address2 => xml.search('ToAddress1').text,
+        :city     => xml.search('ToCity').text,
+        :state    => xml.search('ToState').text,
+        :zip5     => xml.search('ToZip5').text,
+        :zip4     => xml.search('ToZip4').text
+      )
+    end
+  end
+end

data/lib/usps/response/tracking_lookup.rb

@@ -0,0 +1,19 @@
+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 TrackingLookup < Base
+
+    attr_accessor :summary, :details
+
+    def initialize(xml)
+      @summary = xml.search("TrackSummary").text
+
+      @details = []
+      xml.search("TrackDetail").each do |detail|
+        @details << detail.text
+      end
+    end
+
+  end
+end

data/lib/usps/test.rb

@@ -0,0 +1,34 @@
+require 'test/unit'
+require 'rubygems'
+
+module USPS
+  # This class is a test runner for the various test requests that are outlined
+  # in the USPS API documentation. These tests are often used to determine if a
+  # developer is allowed to gain access to the production systems.
+  #
+  # Running this test suite should fullfil all requirements for access to the production
+  # system for the APIs supported by the library.
+  class Test < Test::Unit::TestCase
+    require 'usps/test/zip_code_lookup'
+    require 'usps/test/address_verification'
+    require 'usps/test/city_and_state_lookup'
+    require 'usps/test/tracking_lookup'
+
+    if(ENV['USPS_USER'].nil?)
+      raise 'USPS_USER must be set in the environment to run these tests'
+    end
+
+    USPS.configure do |config|
+      # Being explicit even though it's set in the configuration by default
+      config.username = ENV['USPS_USER']
+
+      # Set USPS_LIVE to anything to run against production
+      config.testing  = true
+    end
+
+    include ZipCodeLookup
+    include CityAndStateLookup
+    include AddressVerification
+    include TrackingLookup
+  end
+end

data/lib/usps/test/address_verification.rb

@@ -0,0 +1,31 @@
+class USPS::Test
+  module AddressVerification
+    def test_address_standardization_1
+      address = USPS::Address.new(
+        :address => '6406 Ivy Lane',
+        :city => 'Greenbelt',
+        :state => 'MD'
+      ).standardize!
+      
+      assert_equal '6406 IVY LN', address.address
+      assert_equal 'GREENBELT', address.city
+      assert_equal 'MD', address.state
+      assert_equal '20770', address.zip5
+      assert_equal '1440', address.zip4
+    end
+
+    def test_address_standardization_2
+      address = USPS::Address.new(
+        :address => '8 Wildwood Drive',
+        :city => 'Old Lyme',
+        :state => 'CT'
+      ).standardize!
+
+      assert_equal '8 WILDWOOD DR', address.address
+      assert_equal 'OLD LYME', address.city
+      assert_equal 'CT', address.state
+      assert_equal '06371', address.zip5
+      assert_equal '1844', address.zip4
+    end
+  end
+end