corgibytes-tax_cloud 0.9.0

data/lib/tax_cloud/cart_item.rb

@@ -0,0 +1,26 @@
+module TaxCloud #:nodoc:
+  # A <tt>CartItem</tt> defines a single line item for the purchase. Used to calculate the tax amount.
+  class CartItem < Record
+    # The unique index number for the line item. Must be unique for the scope of the cart.
+    attr_accessor :index
+    # The stock keeping unit (SKU) number.
+    attr_accessor :item_id
+    # The taxable information code. See TaxCloud::TaxCodes.
+    attr_accessor :tic
+    # The price of the item. All prices are USD. Do not include currency symbol.
+    attr_accessor :price
+    # The total number of items.
+    attr_accessor :quantity
+
+    # Convert the object to a usable hash for SOAP requests.
+    def to_hash
+      {
+        'Index' => index,
+        'ItemID' => item_id,
+        'TIC' => tic,
+        'Price' => price,
+        'Qty' => quantity
+      }
+    end
+  end
+end

data/lib/tax_cloud/client.rb

@@ -0,0 +1,60 @@
+module TaxCloud #:nodoc:
+  # A <tt>Client</tt> communicates with the TaxCloud service.
+  class Client < Savon::Client
+    # Create a new client.
+    def initialize
+      super TaxCloud::WSDL_URL
+
+      if client_params.key?(:read_timeout)
+        http.read_timeout = client_params[:read_timeout]
+      end
+
+      if client_params.key?(:open_timeout)
+        http.open_timeout = client_params[:open_timeout]
+      end
+    end
+
+    # Make a safe SOAP call.
+    # Will raise a TaxCloud::Errors::SoapError on error.
+    #
+    # === Parameters
+    # [method] SOAP method.
+    # [body] Body content.
+    def request(method, body = {})
+      safe do
+        super method, :body => body.merge(auth_params)
+      end
+    end
+
+    # Ping the TaxCloud service.
+    #
+    # Returns "OK" or raises an error if the TaxCloud service is unreachable.
+    def ping
+      TaxCloud::Responses::Ping.parse request(:ping)
+    end
+
+    private
+
+    # Authorization hash to use with all SOAP requests
+    def auth_params
+      return {} unless TaxCloud.configuration
+      {
+        'apiLoginID' => TaxCloud.configuration.api_login_id,
+        'apiKey' => TaxCloud.configuration.api_key
+      }
+    end
+
+    def client_params
+      { wsdl: TaxCloud::WSDL_URL }.tap do |params|
+        params[:open_timeout] = TaxCloud.configuration.open_timeout if TaxCloud.configuration.open_timeout
+        params[:read_timeout] = TaxCloud.configuration.read_timeout if TaxCloud.configuration.read_timeout
+      end
+    end
+
+    def safe
+      yield
+    rescue Savon::SOAP::Fault => e
+      raise TaxCloud::Errors::SoapError.new(e)
+    end
+  end
+end

data/lib/tax_cloud/configuration.rb

@@ -0,0 +1,28 @@
+module TaxCloud #:nodoc:
+  # TaxCloud gem configuration.
+  class Configuration
+    # TaxCloud login ID.
+    attr_accessor :api_login_id
+    # TaxCloud API key.
+    attr_accessor :api_key
+    # Optional USPS username.
+    attr_accessor :usps_username
+    # Savon client option open_timeout.
+    attr_accessor :open_timeout
+    # Savon client option read_timeout.
+    attr_accessor :read_timeout
+
+    def initialize
+      @open_timeout = 2
+      @read_timeout = 2
+    end
+
+    # Check the configuration.
+    #
+    # Will raise a TaxCloud::Errors::MissingConfigOption if any of the API login ID or the API key are missing.
+    def check!
+      raise TaxCloud::Errors::MissingConfigOption.new('api_login_id') unless api_login_id && !api_login_id.strip.empty?
+      raise TaxCloud::Errors::MissingConfigOption.new('api_key') unless api_key && !api_key.strip.empty?
+    end
+  end
+end

data/lib/tax_cloud/errors.rb

@@ -0,0 +1,6 @@
+require 'tax_cloud/errors/tax_cloud_error'
+require 'tax_cloud/errors/missing_config_error'
+require 'tax_cloud/errors/missing_config_option_error'
+require 'tax_cloud/errors/soap_error'
+require 'tax_cloud/errors/unexpected_soap_response_error'
+require 'tax_cloud/errors/api_error'

data/lib/tax_cloud/errors/api_error.rb

@@ -0,0 +1,17 @@
+
+module TaxCloud #:nodoc:
+  module Errors #:nodoc:
+    # This error is raised when the TaxCloud service
+    # returns an error from an API.
+    class ApiError < TaxCloudError
+      # === Parameters
+      # [message] Error message.
+      # [raw] Raw data from the SOAP response.
+      def initialize(message, raw)
+        super(compose_message('api_error',
+                              message: message,
+                              raw: raw))
+      end
+    end
+  end
+end

data/lib/tax_cloud/errors/missing_config_error.rb

@@ -0,0 +1,13 @@
+
+module TaxCloud #:nodoc:
+  module Errors #:nodoc:
+    # This error is raised when attempting to create a new client
+    # without configuring TaxCloud.
+    class MissingConfig < TaxCloudError
+      # Create a new error.
+      def initialize
+        super(compose_message('missing_config'))
+      end
+    end
+  end
+end

data/lib/tax_cloud/errors/missing_config_option_error.rb

@@ -0,0 +1,19 @@
+
+module TaxCloud #:nodoc:
+  module Errors #:nodoc:
+    # This error is raised when a configuration
+    # option is missing.
+    class MissingConfigOption < TaxCloudError
+      # === Parameters
+      # [name] The attempted config option name.
+      def initialize(name)
+        super(
+          compose_message(
+            'missing_config_option',
+            name: name
+          )
+        )
+      end
+    end
+  end
+end

data/lib/tax_cloud/errors/soap_error.rb

@@ -0,0 +1,30 @@
+
+module TaxCloud #:nodoc:
+  module Errors #:nodoc:
+    # This error is raised when a SOAP call fails.
+    class SoapError < TaxCloudError
+      # Original SOAP failt.
+      attr_reader :fault
+
+      # Create the new error.
+      # === Parameters
+      # [e] SOAP response.
+      def initialize(e)
+        @fault = e
+        e.to_hash.tap do |fault|
+          fault_code = fault[:fault][:faultcode]
+          fault_string = parse_fault(fault[:fault][:faultstring])
+          super(compose_message('soap_error',
+                                message: fault_string,
+                                code: fault_code))
+        end
+      end
+
+      private
+
+      def parse_fault(fault_string)
+        fault_string.lines.first.strip
+      end
+    end
+  end
+end

data/lib/tax_cloud/errors/tax_cloud_error.rb

@@ -0,0 +1,83 @@
+
+module TaxCloud #:nodoc:
+  module Errors #:nodoc:
+    # Default parent TaxCloud error for all custom errors. This handles the base
+    # key for the translations and provides the convenience method for
+    # translating the messages.
+    #
+    # Generously borrowed from Mongoid[https://github.com/mongoid/mongoid/blob/master/lib/mongoid/errors/mongoid_error.rb].
+    class TaxCloudError < StandardError
+      # Problem occurred.
+      attr_reader :problem
+
+      # Summary of the problem.
+      attr_reader :summary
+
+      # Suggested problem resolution.
+      attr_reader :resolution
+
+      # Compose the message.
+      # === Parameters
+      # [key] Lookup key in the translation table.
+      # [attributes] The objects to pass to create the message.
+      def compose_message(key, attributes = {})
+        @problem = create_problem(key, attributes)
+        @summary = create_summary(key, attributes)
+        @resolution = create_resolution(key, attributes)
+
+        "\nProblem:\n  #{@problem}" \
+        "\nSummary:\n  #{@summary}" \
+        "\nResolution:\n  #{@resolution}"
+      end
+
+      private
+
+      BASE_KEY = 'taxcloud.errors.messages'.freeze #:nodoc:
+
+      # Given the key of the specific error and the options hash, translate the
+      # message.
+      #
+      # === Parameters
+      # [key] The key of the error in the locales.
+      # [options] The objects to pass to create the message.
+      #
+      # Returns a localized error message string.
+      def translate(key, options)
+        ::I18n.translate("#{BASE_KEY}.#{key}", { locale: :en }.merge(options)).strip
+      end
+
+      # Create the problem.
+      #
+      # === Parameters
+      # [key] The error key.
+      # [attributes] The attributes to interpolate.
+      #
+      # Returns the problem.
+      def create_problem(key, attributes)
+        translate("#{key}.message", attributes)
+      end
+
+      # Create the summary.
+      #
+      # === Parameters
+      # [key] The error key.
+      # [attributes] The attributes to interpolate.
+      #
+      # Returns the summary.
+      def create_summary(key, attributes)
+        translate("#{key}.summary", attributes)
+      end
+
+      # Create the resolution.
+      #
+      # === Parameters
+      # [key] The error key.
+      # [attributes] The attributes to interpolate.
+      #
+      # Returns the resolution.
+      def create_resolution(key, attributes)
+        translate("#{key}.resolution", attributes)
+      end
+    end
+  end
+end

data/lib/tax_cloud/errors/unexpected_soap_response_error.rb

@@ -0,0 +1,19 @@
+
+module TaxCloud #:nodoc:
+  module Errors #:nodoc:
+    # This error is raised when TaxCloud returns an
+    # unexpected SOAP response.
+    class UnexpectedSoapResponse < TaxCloudError
+      # === Parameters
+      # [raw] Raw data from the SOAP response.
+      # [key] Expected key in the SOAP response.
+      # [chain] Complete SOAP response chain in which the key could not be found.
+      def initialize(raw, key, chain)
+        super(compose_message('unexpected_soap_response',
+                              key: key,
+                              raw: raw,
+                              chain: chain))
+      end
+    end
+  end
+end

data/lib/tax_cloud/record.rb

@@ -0,0 +1,14 @@
+module TaxCloud #:nodoc:
+  # A generic TaxCloud record.
+  class Record
+    # Initialize the record.
+    #
+    # === Parameters
+    # [attrs] Attributes defined for this record.
+    def initialize(attrs = {})
+      attrs.each do |sym, val|
+        send "#{sym}=", val
+      end
+    end
+  end
+end

data/lib/tax_cloud/responses.rb

@@ -0,0 +1,13 @@
+require 'tax_cloud/responses/base'
+require 'tax_cloud/responses/generic'
+require 'tax_cloud/responses/ping'
+require 'tax_cloud/responses/verify_address'
+require 'tax_cloud/responses/cart_item'
+require 'tax_cloud/responses/lookup'
+require 'tax_cloud/responses/authorized'
+require 'tax_cloud/responses/authorized_with_capture'
+require 'tax_cloud/responses/captured'
+require 'tax_cloud/responses/returned'
+require 'tax_cloud/responses/tax_codes'
+require 'tax_cloud/responses/tax_code_groups'
+require 'tax_cloud/responses/tax_codes_by_group'

data/lib/tax_cloud/responses/authorized.rb

@@ -0,0 +1,10 @@
+module TaxCloud #:nodoc:
+  module Responses #:nodoc:
+    # Response to a TaxCloud Authorized API call.
+    #
+    # See https://api.taxcloud.net/1.0/TaxCloud.asmx?op=Authorized.
+    class Authorized < Generic
+      response_key :authorized
+    end
+  end
+end

data/lib/tax_cloud/responses/authorized_with_capture.rb

@@ -0,0 +1,10 @@
+module TaxCloud #:nodoc:
+  module Responses #:nodoc:
+    # Response to a TaxCloud AuthorizedWithCapture API call.
+    #
+    # See https://api.taxcloud.net/1.0/TaxCloud.asmx?op=AuthorizedWithCapture.
+    class AuthorizedWithCapture < Generic
+      response_key :authorized_with_capture
+    end
+  end
+end

data/lib/tax_cloud/responses/base.rb

@@ -0,0 +1,82 @@
+module TaxCloud #:nodoc:
+  module Responses #:nodoc:
+    # A base TaxCloud SOAP response.
+    class Base
+      # Raw response.
+      attr_accessor :raw
+
+      # === Parameters
+      # [savon_response] Response from a SOAP API call.
+      def initialize(savon_response)
+        @raw = savon_response.to_hash
+        parse!
+      end
+
+      class << self
+        # === Parameters
+        # [value] Location of the response type in the SOAP XML.
+        def response_type(value)
+          set_dsl(:response_type, value)
+        end
+
+        # === Parameters
+        # [value] Location of the error message in the SOAP XML.
+        def error_message(value)
+          set_dsl(:error_message, value)
+        end
+
+        # === Parameters
+        # [value] Location of the error number in the SOAP XML.
+        def error_number(value)
+          set_dsl(:error_number, value)
+        end
+
+        # Parse a SOAP response.
+        #
+        # === Parameters
+        # [savon_response] SOAP response.
+        def parse(savon_response)
+          new(savon_response)
+        end
+      end
+
+      # Match an element in the SOAP response.
+      #
+      # === Parameters
+      # [chain] XML path to match.
+      def match(chain)
+        current_value = raw
+        chain.split('/').each do |key|
+          current_value = current_value[key.to_sym]
+          next if current_value
+          raise TaxCloud::Errors::UnexpectedSoapResponse.new(raw, key, chain)
+        end
+        current_value
+      end
+
+      private
+
+      class_attribute :dsl
+
+      class << self
+        def set_dsl(key, value)
+          self.dsl ||= {}
+          self.dsl[key] = value
+          self.dsl
+        end
+      end
+
+      def parse!
+        if self.dsl[:response_type]
+          case match(self.dsl[:response_type])
+          when 'OK', 'Informational' then
+            return true
+          end
+        elsif self.dsl[:error_number]
+          return true if match(self.dsl[:error_number]) == '0'
+        end
+        raise TaxCloud::Errors::ApiError.new(match(self.dsl[:error_message]), raw) if self.dsl[:error_message]
+      end
+    end
+  end
+end