tax_cloud 0.1.4 → 0.2.0

data/lib/tax_cloud.rb

@@ -1,44 +1,71 @@
 require 'savon'
-require 'savon_xml_override'
+require 'i18n'
+require 'hash'
+require 'savon_soap_xml'
+require 'active_support/core_ext'
+
 require 'tax_cloud/version'
+require 'tax_cloud/errors'
+require 'tax_cloud/responses'
+require 'tax_cloud/record'
 require 'tax_cloud/transaction'
 require 'tax_cloud/address'
 require 'tax_cloud/cart_item'
+require 'tax_cloud/tax_code'
+require 'tax_cloud/tax_code_group'
 require 'tax_cloud/tax_codes'
+require 'tax_cloud/tax_code_constants'
+require 'tax_cloud/tax_code_groups'
+require 'tax_cloud/tax_code_group_constants'
 require 'tax_cloud/configuration'
-require 'hash'
+require 'tax_cloud/client'
+
+I18n.load_path << File.join(File.dirname(__FILE__), "config", "locales", "en.yml")
 
 # TaxCloud is a web service to calculate and track sales tax for your ecommerce platform. Integration is easy to use.
 # For information on configuring and using the TaxCloud API, look at the <tt>README</tt> file.
 module TaxCloud
-  # WSDL location for TaxCloud
+
+  # WSDL location for TaxCloud API.
   WSDL_URL = 'https://api.taxcloud.net/1.0/?wsdl'
-  # TaxCloud API version
+
+  # TaxCloud API version.
   API_VERSION = '1.0'
 
   class << self
+
+    # TaxCloud gem configuration.
     attr_accessor :configuration
 
-    # Configure the variables
+    # Returns true if the gem has been configured.
+    def configured?
+      !! self.configuration
+    end
+
+    # Configure the gem.
     def configure
       self.configuration ||= Configuration.new
       yield configuration
     end
 
-    # Method to define and retrieve the SOAP methods
-    def client
-      @@client ||= Savon::Client.new do
-        wsdl.document = TaxCloud::WSDL_URL
-      end
+    # Reset the current configuration.
+    def reset!
+      self.configuration = nil
     end
 
-    # Authorization hash to use with all SOAP requests
-    def auth_params
-      {
-        'apiLoginID' => configuration.api_login_id,
-        'apiKey' => configuration.api_key
-      }
+    # The configured SOAP client to the TaxCloud service.
+    def client
+      check_configuration!
+      @@client ||= TaxCloud::Client.new
     end
+
+    private
+
+      def check_configuration!
+        raise TaxCloud::Errors::MissingConfig.new unless self.configuration
+        self.configuration.check!
+      end
+
   end
 
 end

data/lib/tax_cloud/address.rb

@@ -1,24 +1,37 @@
-module TaxCloud
-  # An address
-  class Address
-    attr_accessor :address1, :address2, :city, :state, :zip5, :zip4
+module TaxCloud #:nodoc:
+  # An <tt>Address</tt> defines an address in the United States.
+  class Address < Record
 
-    # Initialize the object with the given variables
-    def initialize(attrs = {})
-      attrs.each do |sym, val|
-        self.send "#{sym}=", val
-      end
-      super
-    end
+    # First line of address.
+    attr_accessor :address1
+    # Second line of adress.
+    attr_accessor :address2
+    # City.
+    attr_accessor :city
+    # State.
+    attr_accessor :state
+    # 5-digit Zip Code.
+    attr_accessor :zip5
+    # 4-digit Zip Code.
+    attr_accessor :zip4
 
-    # Verify the address via TaxCloud
+    # Verify this address.
+    #
+    # Returns a verified TaxCloud::Address.
     def verify
-      request_params = {
-        'apiLoginId' => TaxCloud.configuration.api_login_id,
-        'apiKey' => TaxCloud.configuration.api_key,
+      params = to_hash.downcase_keys
+      params = params.merge({
         'uspsUserID' => TaxCloud.configuration.usps_username
-      }.merge(to_hash.downcase_keys!)
-      response = TaxCloud.client.request :verify_address, :body => request_params
+      }) if TaxCloud.configuration.usps_username
+      response = TaxCloud.client.request(:verify_address, params)
+      TaxCloud::Responses::VerifyAddress.parse(response)
+    end
+
+    # Complete zip code.
+    # Returns a 9-digit Zip Code, when available.
+    def zip
+      return nil unless zip5 && zip5.length > 0
+      [ zip5, zip4 ].select { |z| z && z.length > 0 }.join("-")
     end
 
     # Convert the object to a usable hash for SOAP requests

data/lib/tax_cloud/cart_item.rb

@@ -1,25 +1,19 @@
-require 'builder'
-
-module TaxCloud
+module TaxCloud #:nodoc:
   # A <tt>CartItem</tt> defines a single line item for the purchase. Used to calculate the tax amount.
-  #
-  # === Attributes
-  # * <tt>index</tt> - The unique index number for the line item. Must be unique for the scope of the cart.
-  # * <tt>item_id</tt> - The stock keeping unit (SKU) number
-  # * <tt>tic</tt> - The taxable information code. See <tt>TaxCloud::TaxCodes</tt>.
-  # * <tt>price</tt> - The price of the item. All prices are USD. Do not include currency symbol.
-  # * <tt>quantity</tt> - The total number of items.
-  class CartItem
-    attr_accessor :index, :item_id, :tic, :price, :quantity
+  class CartItem < Record
 
-    def initialize(attrs = {})
-      attrs.each do |sym, val|
-        self.send "#{sym}=", val
-      end
-      super
-    end
+    # 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
+    # Convert the object to a usable hash for SOAP requests.
     def to_hash
       {
         'Index' => index,

data/lib/tax_cloud/client.rb

@@ -0,0 +1,48 @@
+module TaxCloud #:nodoc:
+  # A <tt>Client</tt> communicates with the TaCloud service.
+  class Client < Savon::Client
+
+    # Create a new client.
+    def initialize
+      super TaxCloud::WSDL_URL
+    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
+        {
+          'apiLoginID' => TaxCloud.configuration.api_login_id,
+          'apiKey' => TaxCloud.configuration.api_key
+        }
+      end
+
+      def safe &block
+        begin
+          yield
+        rescue Savon::SOAP::Fault => e
+          raise TaxCloud::Errors::SoapError.new(e)
+        end
+      end
+
+  end
+end

data/lib/tax_cloud/configuration.rb

@@ -1,5 +1,20 @@
-module TaxCloud
+module TaxCloud #:nodoc:
+  # TaxCloud gem configuration.
   class Configuration
-    attr_accessor :api_login_id, :api_key, :usps_username
+
+    # TaxCloud login ID.
+    attr_accessor :api_login_id
+    # TaxCloud API key.
+    attr_accessor :api_key
+    # Optional USPS username.
+    attr_accessor :usps_username
+
+    # 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 self.api_login_id && self.api_login_id.strip.length > 0
+      raise TaxCloud::Errors::MissingConfigOption.new('api_key') unless self.api_key && self.api_key.strip.length > 0
+    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,18 @@
+# encoding: utf-8
+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 @@
+# encoding: utf-8
+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 @@
+# encoding: utf-8
+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,33 @@
+# encoding: utf-8
+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,86 @@
+# encoding: utf-8
+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" #: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,23 @@
+# encoding: utf-8
+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