usps-ruby-client 0.1.0

data/lib/usps/api/endpoints/verify.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# This file was auto-generated by lib/tasks/api.rake
+
+module Usps
+	module Api
+		module Endpoints
+			module Verify
+				#
+				# Address Validation API
+				#
+				#
+				# @option option [(Alias)] :AddressValidateRequest (Required)
+				# - API = AddressValidateRequest
+				#   @option option [String] :Revision (Required)
+				#   - Integer value used to return of all available response fields. Set this value to 1 to return all currently documented response fields. Example: Revision>1</Revision>
+				#   @option option [(group)] :Address (Required)
+				#   - Up to 5 address verifications can be included per transaction.
+				#     @option option [String] :FirmName (Optional)
+				#     - Firm Name Example:<FirmName>XYZ Corp.</FirmName>
+				#     @option option [String] :Address1 (Optional)
+				#     - Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)
+				#     @option option [String] :Address2 (Required)
+				#     - Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in the Detail 1 Record.
+				#     @option option [String] :City (Optional)
+				#     - City name of the destination address.
+				#     @option option [String] :State (Optional)
+				#     - Two-character state code of the destination address.
+				#     @option option [String] :Urbanization (Optional)
+				#     - Urbanization. For Puerto Rico addresses only.
+				#     @option option [String] :Zip5 (Optional)
+				#     - Destination 5-digit ZIP Code. Numeric values (0-9) only. If International, all zeroes.
+				#     @option option [String] :Zip4 (Optional)
+				#     - Destination ZIP+4 Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.
+
+				#
+				# @see 
+				def verify(options = {})
+					throw ArgumentError.new('Required arguments :address_validate_request missing') if options[:address_validate_request].nil?
+					throw ArgumentError.new('Required arguments :address_validate_request, :revision missing') if options[:address_validate_request][:revision].nil?
+					throw ArgumentError.new('Required arguments :address_validate_request, :address missing') if options[:address_validate_request][:address].nil?
+					throw ArgumentError.new('Required arguments :address_validate_request, :address, :address2 missing') if options[:address_validate_request][:address][:address2].nil?
+
+					request = build_request(:verify, options)
+					get('https://secure.shippingapis.com/ShippingAPI.dll', {
+						API: 'Verify',
+						XML: request,
+					})
+				end
+
+				private
+
+				def tag_unless_blank(xml, tag_name, data)
+					xml.tag!(tag_name, data) unless data.blank? || data.nil?
+				end
+
+				def build_verify_request(xml, options = {})
+					xml.tag!('Revision', options[:address_validate_request][:revision])
+					xml.tag!('Address') do
+						tag_unless_blank(xml, 'FirmName', options[:address_validate_request][:address][:firm_name])
+						tag_unless_blank(xml, 'Address1', options[:address_validate_request][:address][:address1])
+						xml.tag!('Address2', options[:address_validate_request][:address][:address2])
+						tag_unless_blank(xml, 'City', options[:address_validate_request][:address][:city])
+						tag_unless_blank(xml, 'State', options[:address_validate_request][:address][:state])
+						tag_unless_blank(xml, 'Urbanization', options[:address_validate_request][:address][:urbanization])
+						tag_unless_blank(xml, 'Zip5', options[:address_validate_request][:address][:zip5])
+						tag_unless_blank(xml, 'Zip4', options[:address_validate_request][:address][:zip4])
+					end 
+					xml.target!
+				end
+
+			end
+		end
+	end
+end

data/lib/usps/api/endpoints/zip_code_lookup.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# This file was auto-generated by lib/tasks/api.rake
+
+module Usps
+	module Api
+		module Endpoints
+			module ZipCodeLookup
+				#
+				# ZIP Code Lookup API
+				#
+				# The ZipCodeLookup API, which returns the ZIP Code and ZIP
+				# Code + 4 corresponding to the given address, city, and state (use USPS state
+				# abbreviations). The ZipCodeLookup API processes up to
+				# five lookups per request.
+				#
+				# @option option [(Alias)] :ZipCodeLookupRequest (Required)
+				# - API = ZipCodeLookupRequest
+				#   @option option [(Group)] :Address (Optional)
+				#     @option option [String] :FirmName (Optional)
+				#     - Up to 5 address verifications can be included per transaction.
+				#     @option option [String] :Address1 (Optional)
+				#     - Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)
+				#     @option option [String] :Address2 (Required)
+				#     - Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in the Detail 1 Record.
+				#     @option option [String] :City (Optional)
+				#     - City name of the destination address. Field is required, unless a verified 11-digit DPV is provided for the mail piece.
+				#     @option option [String] :State (Optional)
+				#     - Two-character state code of the destination address.
+				#     @option option [String] :Zip5 (Optional)
+				#     - Destination 5-digit ZIP Code. Must be 5-digits. Numeric values (0-9) only. If International, all zeroes.
+				#     @option option [String] :Zip4 (Optional)
+				#     - Destination ZIP+4. Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.
+
+				#
+				# @see 
+				def zip_code_lookup(options = {})
+					throw ArgumentError.new('Required arguments :zip_code_lookup_request missing') if options[:zip_code_lookup_request].nil?
+
+					request = build_request(:zip_code_lookup, options)
+					get('https://secure.shippingapis.com/ShippingAPI.dll', {
+						API: 'ZipCodeLookup',
+						XML: request,
+					})
+				end
+
+				private
+
+				def tag_unless_blank(xml, tag_name, data)
+					xml.tag!(tag_name, data) unless data.blank? || data.nil?
+				end
+
+				def build_zip_code_lookup_request(xml, options = {})
+					xml.tag!('Address') do
+						tag_unless_blank(xml, 'FirmName', options[:zip_code_lookup_request][:address][:firm_name])
+						tag_unless_blank(xml, 'Address1', options[:zip_code_lookup_request][:address][:address1])
+						xml.tag!('Address2', options[:zip_code_lookup_request][:address][:address2])
+						tag_unless_blank(xml, 'City', options[:zip_code_lookup_request][:address][:city])
+						tag_unless_blank(xml, 'State', options[:zip_code_lookup_request][:address][:state])
+						tag_unless_blank(xml, 'Zip5', options[:zip_code_lookup_request][:address][:zip5])
+						tag_unless_blank(xml, 'Zip4', options[:zip_code_lookup_request][:address][:zip4])
+					end if options[:zip_code_lookup_request][:address].present?
+					xml.target!
+				end
+
+			end
+		end
+	end
+end

data/lib/usps/api/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+module Usps
+  module Api
+    Error = Errors::UspsError
+  end
+end

data/lib/usps/api/errors/too_many_requests_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+module Usps
+  module Api
+    module Errors
+      class TooManyRequestsError < ::Faraday::Error
+        attr_reader :response
+
+        def initialize(response)
+          @response = response
+        end
+
+        def message
+          "Retry after #{retry_after} seconds"
+        end
+
+        def retry_after
+          response.headers['retry-after'].to_i
+        end
+      end
+    end
+  end
+end

data/lib/usps/api/errors/usps_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+module Usps
+  module Api
+    module Errors
+      class UspsError < ::Faraday::Error
+        attr_reader :response
+
+        def initialize(error, response = nil)
+          super error['Description']
+          @error_number = error['Number']
+          @error_description = error['Description']
+          @error_source = error['Source']
+          @response = response
+        end
+
+        def error
+          response.body.error
+        end
+
+        def errors
+          response.body.errors
+        end
+
+        def response_metadata
+          response.body.response_metadata
+        end
+      end
+    end
+  end
+end

data/lib/usps/api/templates/_build_xml.erb

@@ -0,0 +1,7 @@
+<% if option[:children].blank? %>
+<% if option[:required] %>
+<% indentation.times do %><%= "\t" %><% end %>xml.tag!('<%= option[:name] %>', options<% parents.each do |parent| %>[:<%= parent %>]<% end %>[:<%= option[:name].underscore %>])<% else %><% indentation.times do %><%= "\t" %><% end %>tag_unless_blank(xml, '<%= option[:name] %>', options<% parents.each do |parent| %>[:<%= parent %>]<% end %>[:<%= option[:name].underscore %>])<% end %><% else %><% indentation.times do %><%= "\t" %><% end %>xml.tag!('<%= option[:name] %>') do
+	<% option[:children].each do |child_option_name, child_option| %>
+	<%= Erubis::Eruby.new(File.read('lib/usps/api/templates/_build_xml.erb')).result(option: child_option, parents: parents + [option[:name].underscore], indentation: indentation + 1) %>
+	<% end %>
+<% (indentation+1).times do %><%= "\t" %><% end %>end <% if !option[:required] %>if options<% parents.each do |parent| %>[:<%= parent %>]<% end %>[:<%= option[:name].underscore %>].present?<% end %><% end %>

data/lib/usps/api/templates/_options.erb

@@ -0,0 +1,6 @@
+<%= ErubisHelper.tabs(static_indentation) %>#<%= ErubisHelper.spaces(indentation*2) %>@option option [<%= option[:type] %>] :<%= option[:name] %> (<%= option[:required] ? 'Required' : 'Optional' %>)
+<% if option[:description].present? %>
+<%= ErubisHelper.tabs(static_indentation) %>#<%= ErubisHelper.spaces(indentation*2) %>- <%= option[:description] %>
+<% end %>
+<% option[:children].each do |child_option_name, child_option| %>
+<%= Erubis::Eruby.new(File.read('lib/usps/api/templates/_options.erb')).result(option: child_option, parents: [], indentation: indentation + 1, static_indentation: static_indentation) %><% end %>

data/lib/usps/api/templates/_throw_argument_error.erb

@@ -0,0 +1,3 @@
+<%= ErubisHelper.tabs(indentation) %>throw ArgumentError.new('Required arguments <% parents.each do |parent| %>:<%= parent %>, <% end %>:<%= option[:name].underscore %> missing') if options<% parents.each do |parent| %>[:<%= parent %>]<% end %>[:<%= option[:name].underscore %>].nil?
+<% option[:children].select{|n,o| o[:required]}.each do |child_option_name, child_option| %>
+	<%= Erubis::Eruby.new(File.read('lib/usps/api/templates/_throw_argument_error.erb')).result(option: child_option, parents: parents + [option[:name].underscore], indentation: indentation) %><% end %>

data/lib/usps/api/templates/endpoints.erb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# This file was auto-generated by lib/tasks/web.rake
+
+<% files.each do |f| %>
+require_relative 'endpoints/<%= f[:file] %>'
+<% end %>
+
+module Usps
+  module Api
+    module Endpoints
+<% files.each do |f| %>
+      include <%= f[:module] %>
+<% end %>
+
+      ACTIONS = {
+<% files.each do |f| %>
+        <%= f[:file] %>: '<%= f[:module] %>',
+<% end %>
+      }.freeze
+    end
+  end
+end

data/lib/usps/api/templates/method.erb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# This file was auto-generated by lib/tasks/api.rake
+
+module Usps
+	module Api
+		module Endpoints
+			module <%= data[:group].camelize %>
+				#
+				# <%= data[:title] %>
+				#
+				<% data[:description].to_s.split("\r").each do |line| %>
+				# <%= line.strip %>
+				<% end %>
+				#
+				<% data[:request_descriptions].each do |option_name, option| %>
+<%= Erubis::Eruby.new(File.read('lib/usps/api/templates/_options.erb')).result(option: option, parents: [], indentation: 0, static_indentation: 3) %><% end %>
+				#
+				# @see <%= data[:link] %>
+				def <%= data[:group].underscore %>(options = {})
+					<% data[:request_descriptions].select{|n,o| o[:required]}.each do |option_name, option| %>
+	<%= Erubis::Eruby.new(File.read('lib/usps/api/templates/_throw_argument_error.erb')).result(option: option, parents: [], indentation: 3) %>
+					<% end %>
+					request = build_request(:<%= data[:group].underscore %>, options)
+					get('<%= data[:url] %>', {
+						API: '<%= data[:group] %>',
+						XML: request,
+					})
+				end
+
+				private
+
+				def tag_unless_blank(xml, tag_name, data)
+					xml.tag!(tag_name, data) unless data.blank? || data.nil?
+				end
+
+				def build_<%= data[:group].underscore %>_request(xml, options = {})
+					<% data[:request_descriptions].each do |option_name, option| %>
+						<% option[:children].each do |child_option_name, child_option| %>
+	<%= Erubis::Eruby.new(File.read('lib/usps/api/templates/_build_xml.erb')).result(option: child_option, parents: [option[:name].underscore], indentation: 4) %>
+						<% end %>
+					<% end %>
+					xml.target!
+				end
+
+			end
+		end
+	end
+end

data/lib/usps/api/templates/method_spec.erb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# This file was auto-generated by lib/tasks/api.rake
+
+require 'spec_helper'
+
+RSpec.describe Usps::Api::Endpoints::<%= data[:group].camelize %> do
+  let(:client) { Usps::Client.new }
+<% [data[:group]].sort.each_with_index do |(name), index| %>
+<% next if data['mixin'] %>
+<% required_params = data[:request_descriptions].select{|n,o| o[:required]} %>
+<% next if required_params.none? %>
+  context '<%= data[:group].underscore %>' do
+<% required_params.each do |arg_name, arg_v| %>
+    it 'requires <%= arg_name.underscore %>' do
+<% params_except_required = required_params.reject{ |name, _| name == arg_name  }.map{|var, opts| "#{var}: '#{opts['example']}'"}.join(', ') %>
+      expect { client.<%= group.underscore %><%= params_except_required.empty? ? '' : "(#{params_except_required})" %> }.to raise_error ArgumentError, /Required arguments :<%= arg_name.underscore %> missing/
+    end
+<% end %>
+  end
+<% end %>
+end

data/lib/usps/api/xml.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+module Usps
+  module Api
+    def tag_unless_blank(xml, tag_name, data)
+      xml.tag!(tag_name, data) unless data.blank? || data.nil?
+    end
+  end
+end

data/lib/usps/client.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+module Usps
+  class Client
+    include Faraday::Connection
+    include Faraday::Request
+    include Api::Endpoints
+
+    attr_accessor(*Config::ATTRIBUTES)
+
+    def initialize(options = {})
+      Usps::Config::ATTRIBUTES.each do |key|
+        send("#{key}=", options.fetch(key, Usps.config.send(key)))
+      end
+      @logger ||= Usps::Config.logger || Usps::Logger.default
+      @token ||= Usps.config.token
+      @user_id ||= Usps.config.user_id
+    end
+
+    def build_request(action, options)
+      xml = Builder::XmlMarkup.new(indent: 2)
+      # xml.instruct!(:xml, version: '1.0', encoding: 'utf-8')
+      xml.tag!("#{Usps::Api::Endpoints::ACTIONS[action]}Request", USERID: user_id) do
+        send("build_#{action}_request", xml, options)
+      end
+    end
+
+    class << self
+      def configure
+        block_given? ? yield(Config) : Config
+      end
+
+      def config
+        Config
+      end
+    end
+  end
+end

data/lib/usps/config.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+module Usps
+  module Config
+    extend self
+
+    ATTRIBUTES = %i[
+      proxy
+      user_agent
+      ca_path
+      ca_file
+      logger
+      endpoint
+      user_id
+      token
+      timeout
+      open_timeout
+      default_page_size
+      default_max_retries
+    ].freeze
+
+    attr_accessor(*Config::ATTRIBUTES)
+
+    def reset
+      self.endpoint = 'https://secure.shippingapis.com/'
+      self.user_agent = "USPS Ruby Client/#{Usps::VERSION}"
+      self.ca_path = defined?(OpenSSL) ? OpenSSL::X509::DEFAULT_CERT_DIR : nil
+      self.ca_file = defined?(OpenSSL) ? OpenSSL::X509::DEFAULT_CERT_FILE : nil
+      self.user_id = nil
+      self.token = nil
+      self.proxy = nil
+      self.logger = nil
+      self.timeout = nil
+      self.open_timeout = nil
+      self.default_page_size = 100
+      self.default_max_retries = 100
+    end
+  end
+
+  class << self
+    def configure
+      block_given? ? yield(Config) : Config
+    end
+
+    def config
+      Config
+    end
+  end
+end
+
+Usps::Config.reset

data/lib/usps/faraday/connection.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+module Usps
+  module Faraday
+    module Connection
+      private
+
+      def connection
+        options = {
+          headers: { 'Accept' => 'application/json; charset=utf-8' },
+        }
+
+        options[:headers]['User-Agent'] = user_agent if user_agent
+        options[:proxy] = proxy if proxy
+        options[:ssl] = { ca_path: ca_path, ca_file: ca_file } if ca_path || ca_file
+
+        request_options = {}
+        request_options[:timeout] = timeout if timeout
+        request_options[:open_timeout] = open_timeout if open_timeout
+        options[:request] = request_options if request_options.any?
+
+        ::Faraday::Connection.new(endpoint, options) do |connection|
+          connection.use ::Faraday::Request::Multipart
+          connection.use ::Faraday::Request::UrlEncoded
+          connection.use ::Faraday::Response::RaiseError
+          connection.use ::Usps::Faraday::Response::RaiseError
+          # connection.use ::FaradayMiddleware::Mashify, mash_class: Slack::Messages::Message
+          connection.use ::FaradayMiddleware::ParseXml
+          connection.response :logger, logger if logger
+          connection.adapter ::Faraday.default_adapter
+        end
+      end
+    end
+  end
+end