tax_cloud 0.1.4 → 0.2.0

data/.travis.yml

@@ -0,0 +1,9 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ruby-head
+  - jruby
+  - rbx
+  - ree
+

data/CHANGELOG.rdoc

@@ -0,0 +1,28 @@
+=== 0.2.0 (11/26/2012)
+
+* The gem is now licensed under the MIT license - @dblock.
+* Raise specialized configuration and SOAP errors - @dblock.
+* Added <tt>TaxCloud::Client.ping</tt> - @dblock.
+* Returning a verified <tt>TaxCloud::Address</tt> from <tt>TaxCloud::Address.verify</tt> - @dblock.
+* Added <tt>TaxCloud::Address.zip</tt> that returns a 9-digit address zip code, when available - @dblock.
+* Returning a <tt>TaxCloud::Responses::Lookup</tt> from <tt>TaxCloud::Transaction.lookup</tt> - @dblock.
+* Returning transaction state, ie. <tt>"OK"</tt> from all other TaxCloud transactions. Exceptions are raised on error - @dblock.
+* Added support for tax codes and tax code groups lookup with <tt>TaxCloud::TaxCodes</tt> and <tt>TaxCloud::TaxCode::Groups</tt> - @dblock.
+
+=== 0.1.5 (5/9/2012)
+
+* Fixed compatibility with Ruby 1.8.7 and 1.9.3, removed super from constructors for classes which inherit from <tt>Object</tt> - @gfmurphy.
+
+=== 0.1.4 (10/20/2011)
+
+* Upgraded rdoc - @drewtempelmeyer.
+* Fixed <tt>.gemspec</tt> dependency declaration for savon - @drewtempelmeyer.
+
+=== 0.1.3 (9/19/2011)
+
+* Added support for the "returned" request - @danielmorrison.
+* Refactoreted tests to use vcr and webmock - @danielmorrison.
+
+=== 0.1.0 (8/23/2011)
+
+* Initial public release - @drewtempelmeyer.

data/CONTRIBUTORS.txt

@@ -0,0 +1,20 @@
+tax_cloud Contributors
+
+Lead Developers
+=======================
+* Drew Tempelmeyer
+  * Twitter: @tempelmeyer
+  * App.net: @tempelmeyer
+  * GitHub: drewtempelmeyer
+
+* Daniel Doubrovkine
+  * Twitter: @dblockdotorg
+  * GitHub: dblock
+
+Contributors
+=======================
+* Daniel Morrison
+  * GitHub: danielmorrison
+
+* George F Murphy
+  * GitHub: gfmurphy

data/Gemfile

@@ -1,4 +1,4 @@
 source "http://rubygems.org"
 
-# Specify your gem's dependencies in taxcloud.gemspec
+# Specify your gem's dependencies in tax_cloud.gemspec
 gemspec

data/LICENSE.rdoc

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2011-2012 Drew Tempelmeyer & Contributors
+
+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.rdoc

@@ -1,47 +1,126 @@
 = TaxCloud
 
-TaxCloud is a service to calculate sales tax and generate tax reports.
-tax\_cloud allows you to easily integrate with TaxCloud's API.
+{<img src="https://travis-ci.org/drewtempelmeyer/tax_cloud.png" />}[https://travis-ci.org/drewtempelmeyer/tax_cloud]
+
+TaxCloud[http://www.taxcloud.com] is a free service to calculate sales tax and generate tax reports. The <tt>tax_cloud</tt> gem allows you to easily integrate with TaxCloud's API.
+
+=== Getting Started
+A TaxCloud[http://www.taxcloud.com] API ID and API key are required, along with an optional USPS address API username.
+
+1. Create a TaxCloud[http://www.taxcloud.com] merchant account at http://www.taxcloud.net.
+2. Add a website to your TaxCloud[http://www.taxcloud.com] account. This will generate an API ID and API Key that you will need to use the service.
+3. Get access to the USPS Address API at https://www.usps.com/business/webtools.htm. The API will provide a 9-digit zip code, which allows TaxCloud[http://www.taxcloud.com] to determine the most accurate rate.
 
 === Setup
-Add the gem to your Gemfile
-  gem 'tax_cloud', '~> 0.1.0'
+Add the gem to your Gemfile.
+
+    gem 'tax_cloud', '~> 0.1.5'
 
-Configure your environment. For example, create an initializer in Rails in *config/initializers/tax_cloud.rb*
-  TaxCloud.configure do |config|
-    config.api_login_id = 'your_tax_cloud_api_login_id'
-    config.api_key = 'your_tax_cloud_api_key'
-    config.usps_username = 'your_usps_username'
-  end
+Configure your environment. For example, create an initializer in Rails in <tt>config/initializers/tax_cloud.rb</tt>.
+
+    TaxCloud.configure do |config|
+      config.api_login_id = 'your_tax_cloud_api_login_id'
+      config.api_key = 'your_tax_cloud_api_key'
+      config.usps_username = 'your_usps_username'
+    end
 
 === Using TaxCloud
 Define the destination and origin addresses using <tt>TaxCloud::Address</tt>.
-  origin = TaxCloud::Address.new(:address1 => '123 Fake Street', :city => 'New York', :state => 'NY', :zip5 => '10001')
-  destination = TaxCloud::Address.new(:address1 => '239 Hollywood Drive', :city => 'Beverly Hills', :state => 'CA', :zip5 => '90210')
+
+    origin = TaxCloud::Address.new(
+      :address1 => '162 East Avenue',
+      :address2 => 'Third Floor',
+      :city => 'Norwalk',
+      :state => 'CT',
+      :zip5 => '06851')
+    destination = TaxCloud::Address.new(
+      :address1 => '3121 West Government Way',
+      :address2 => 'Suite 2B',
+      :city => 'Seattle',
+      :state => 'WA',
+      :zip5 => '98199')
 
 Create your Transaction and set up your cart items
-  transaction = TaxCloud::Transaction.new(:customer_id => '1', :cart_id => '1', :origin => origin, :destination => destination)
-  transaction.cart_items << TaxCloud::CartItem.new(:index => 0, :item_id => 'SKU-100', :tic => TaxCloud::TaxCodes::GENERAL, :price => 10.00, :quantity => 1)
-  lookup = transaction.lookup # this will return a Savon response object
+
+    transaction = TaxCloud::Transaction.new(
+      :customer_id => '1',
+      :cart_id => '1',
+      :origin => origin,
+      :destination => destination)
+    transaction.cart_items << TaxCloud::CartItem.new(
+      :index => 0,
+      :item_id => 'SKU-100',
+      :tic => TaxCloud::TaxCodes::GENERAL,
+      :price => 10.00,
+      :quantity => 1)
+    lookup = transaction.lookup # this will return a TaxCloud::Responses::Lookup instance
+    lookup.tax_amount # total tax amount
+    lookup.cart_items.each do |cart_item|
+      cart_item.tax_amount # tax for a single item
+    end
 
 After you've authorized and captured the transaction via your merchant account, you should do the same with TaxCloud for maintaining accurate tax information.
-  transaction.order_id = 100
-  transaction.authorized_with_capture # return Savon response object
 
-Later, you may need to mark some cart items as returned. TaxCloud will ignore any cart items that you don't include
     transaction.order_id = 100
-    transaction.cart_items << TaxCloud::CartItem.new(:index => 0, :item_id => 'SKU-100', :tic => TaxCloud::TaxCodes::GENERAL, :price => 10.00, :quantity => 1)
-    transaction.returned # return Savon response object
+    transaction.authorized_with_capture # returns "OK" or raises an error
 
-=== Running Tests
-* Add your config details to *test/helper*
-* VCR and WebMock are used to replay requests and avoid hitting the API each time. To refresh the mocks, simply delete the *test/cassettes* directory.
-* The mocks will filter out your config details, but remember not to commit them!
-* run <tt>rake test</tt>
+Later, you may need to mark some cart items as returned. TaxCloud will ignore any cart items that you don't include.
+
+    transaction.order_id = 100
+    transaction.cart_items << TaxCloud::CartItem.new(
+      :index => 0,
+      :item_id => 'SKU-100',
+      :tic => TaxCloud::TaxCodes::GENERAL,
+      :price => 10.00,
+      :quantity => 1)
+    transaction.returned # returns "OK" or raises an error
+
+=== Verifying Addresses
+
+TaxCloud[http://www.taxcloud.com] optionally integrates with the USPS Address API. An address can be verified, which can also yield a 9-digit zip code that helps determine a more accurate tax rate.
+
+    address = TaxCloud::Address.new({
+      :address1 => '888 6th Ave',
+      :city => 'New York',
+      :state => 'New York',
+      :zip5 => '10001'
+    })
 
-=== Todo
-* Instead of returning Savon response objects, it should return TransactionLookupResponse, TransactionAuthorizedResponse, TransactionCapturedResponse, etc.
-* Add all tax codes to TaxCloud::TaxCodes
+    verified_address = address.verify
+    verified_address.zip5 # 10001
+    verified_address.zip4 # 3502
+    verified_address.zip # 10001-3502
+
+=== Tax Codes
+TaxCloud[http://www.taxcloud.com] maintains a list of all Taxability Information Codes or TICs, which can be found at https://taxcloud.net/tic.
+
+You can obtain all tax codes as well as lookup a tax code by ID.
+
+    TaxCloud::TaxCodes.all # a hash of all codes
+    tax_code = TaxCloud::TaxCodes[TaxCloud::TaxCodes::DIRECT_MAIL_RELATED]
+    tax_code.ticid # 11000 or TaxCloud::TaxCodes::DIRECT_MAIL_RELATED
+    tax_code.description # "Direct-mail related"
+
+Tax codes are organized in groups.
+
+    TaxCloud::TaxCode::Groups.all # a hash of all groups
+    tax_code_group = TaxCloud::TaxCode::Groups[TaxCloud::TaxCode::Groups::SCHOOL_RELATED_PRODUCTS]
+    tax_code_group.group_id # 3 or TaxCloud::TaxCode::Groups::SCHOOL_RELATED_PRODUCTS
+    tax_code_group.description # School Related Products
+    tax_code_group.tax_codes # a hash of all codes in this group
+
+Tax code constants are defined in <tt>tax_code_constants.rb</tt> and tax code group constants in <tt>tax_code_group_constants.rb</tt>. These files can be generated by running the following rake tasks.
+
+    TAXCLOUD_API_LOGIN_ID=... TAXCLOUD_API_KEY=... TAXCLOUD_USPS_USERNAME=... tax_cloud:tax_codes
+    TAXCLOUD_API_LOGIN_ID=... TAXCLOUD_API_KEY=... TAXCLOUD_USPS_USERNAME=... tax_cloud:tax_code_groups
+
+=== Running Tests
+* VCR and WebMock are used to replay requests and avoid hitting the API each time. To refresh the mocks, simply delete the <tt>test/cassettes</tt> directory.
+* Run tests.
+    rake test
+* If you need to record new requests against TaxCloud, set your keys first.
+    TAXCLOUD_API_LOGIN_ID=... TAXCLOUD_API_KEY=... TAXCLOUD_USPS_USERNAME=... rake test
+  The mocks will filter out your configuration details.
 
 === Bugs, fixes, etc
 * Fork.
@@ -49,3 +128,8 @@ Later, you may need to mark some cart items as returned. TaxCloud will ignore an
 * Fix.
 * Commit.
 * Submit pull request.
+
+=== License
+
+This gem is licened under the MIT license.
+

data/Rakefile

@@ -13,12 +13,20 @@ end
 RDoc::Task.new do |rd|
   README = 'README.rdoc'
   rd.main = README
-  rd.rdoc_files.include(README, "lib/**/*.rb")
+  rd.rdoc_files.include(README, 'CHANGELOG.rdoc', 'LICENSE.rdoc', "lib/**/*.rb")
   rd.rdoc_dir = 'doc'
   rd.title = 'tax_cloud'
 end
 
-desc "Validate the gemspec"
+desc "Validate the gemspec."
 task :gemspec do
   puts gemspec.validate
 end
+
+load 'lib/tasks/tax_cloud.rake'
+load 'lib/tasks/tax_codes.rake'
+load 'lib/tasks/tax_code_groups.rake'
+
+load 'vcr/tasks/vcr.rake'
+
+task :default => :test

data/lib/config/locales/en.yml

@@ -0,0 +1,34 @@
+en:
+  taxcloud:
+    errors:
+      messages:
+        missing_config:
+          message: "Missing configuration."
+          summary: "TaxCloud requires an API login ID and key."
+          resolution: "Create a TaxCloud merchant account at http://www.taxcloud.net.
+            Add a website to your TaxCloud account. This will generate an API ID and 
+            API Key that you will need to use the service. Configure the TaxCloud
+            gem. For example, add the following to `config/initializers/tax_cloud.rb`.\n
+            \_\_TaxCloud.configure do |config|\n
+            \_\_\_config.api_login_id = 'your_tax_cloud_api_login_id'\n
+            \_\_\_config.api_key = 'your_tax_cloud_api_key'\n
+            \_\_\_config.usps_username = 'your_usps_username' # optional\n
+            \_\_end\n"
+        missing_config_option:
+          message: "Missing configuration option: %{name}."
+          summary: "A configuration option was not provided when configuration TaxCloud."
+          resolution: "Review your `TaxCloud.configure` code. Are you using an environment
+          variable that has not been set?"
+        soap_error:
+          message: "%{message}"
+          summary: "The server returned a %{code} error."
+          resolution: "Review the parameters passed to the request."
+        unexpected_soap_response:
+          message: "Expected a value for `%{key}` in `%{chain}` in the TaxCloud response."
+          summary: "TaxCloud returned an unexpected response: `%{raw}`."
+          resolution: "This is possibly a bug in the tax_cloud gem.\n
+          Please report it in https://github.com/drewtempelmeyer/tax_cloud/issues."
+        api_error:
+          message: "%{message}"
+          summary: "The TaxCloud server returned an error in the response: `%{raw}`"
+          resolution: "Check the request parameters."

data/lib/hash.rb

@@ -1,9 +1,11 @@
-class Hash
+class Hash #:nodoc: all
+
   # Downcase the keys. Use this because <tt>TaxCloud::Address.verify</tt> requires downcased keys
-  def downcase_keys!
-    keys.each do |key|
-      self[key.to_s.downcase] = delete(key)
+  def downcase_keys
+    inject({}) do |h, (k, v)|
+      h[k.downcase] = v
+      h
     end
-    self
   end
-end
+
+end

data/lib/savon_soap_xml.rb

@@ -0,0 +1,33 @@
+# Hack Savon to work properly with arrays
+module Savon #:nodoc:
+  module SOAP #:nodoc:
+    class XML #:nodoc:
+      
+      private
+
+        old_add_namespaces_to_body = self.instance_method(:add_namespaces_to_body)
+
+        def add_namespaces_to_body(hash, path = [input[1].to_s])
+          return unless hash
+          return hash if hash.kind_of? Array
+          return hash.to_s unless hash.kind_of? Hash
+
+          hash.inject({}) do |newhash, (key, value)|
+            camelcased_key = Gyoku::XMLKey.create(key)
+            newpath = path + [camelcased_key]
+
+            if used_namespaces[newpath]
+              newhash.merge(
+                "#{used_namespaces[newpath]}:#{camelcased_key}" =>
+                  add_namespaces_to_body(value, types[newpath] ? [types[newpath]] : newpath)
+              )
+            else
+              newhash.merge(key => value)
+            end
+          end
+        end
+
+    end
+  end
+end
+

data/lib/tasks/tax_cloud.rake

@@ -0,0 +1,20 @@
+require 'tax_cloud'
+
+namespace :tax_cloud do
+
+  desc "Configure TaxCloud."
+  task :configure do
+    unless TaxCloud.configured?
+      TaxCloud.configure do |config|
+        config.api_login_id = ENV['TAXCLOUD_API_LOGIN_ID']
+        config.api_key = ENV['TAXCLOUD_API_KEY']
+        config.usps_username = ENV['TAXCLOUD_USPS_USERNAME']
+      end  
+      Savon.configure do |config|
+        config.log = false
+      end
+      HTTPI.log = false
+    end
+  end
+
+end

data/lib/tasks/tax_code_groups.rake

@@ -0,0 +1,39 @@
+namespace :tax_cloud do
+
+  desc "Generate tax code groups."
+  task :tax_code_groups => :configure do
+    filename = "lib/tax_cloud/tax_code_group_constants.rb"
+
+    begin
+      groups = TaxCloud::TaxCode::Groups.all.values
+
+      File.open filename, "wt" do |f|
+        f.write "module TaxCloud\n"
+        f.write "  class TaxCode\n"
+        f.write "    # Tax Code Groups.\n"
+        f.write "    class Groups\n"
+
+        groups.each do |group|
+          puts " #{group.description}"
+          code = group.description.upcase
+          code.gsub! /[^A-Z0-9]/, '_'
+          code.gsub! /_$/, ''
+          code.gsub! /\_+/, '_'
+          f.write "      \# #{group.description}\n"
+          f.write "      #{code} = #{group.group_id}\n"
+        end
+
+        f.write "    end\n"
+        f.write "  end\n"
+        f.write "end\n"
+      end
+
+      puts "Done, #{filename}."
+    rescue => e
+      puts "ERROR: Unable to generate a new list of tax codes."
+      puts e.message
+      raise e
+    end
+  end
+
+end

data/lib/tasks/tax_codes.rake

@@ -0,0 +1,45 @@
+namespace :tax_cloud do
+
+  desc "Generate tax codes."
+  task :tax_codes => :configure do
+    filename = "lib/tax_cloud/tax_code_constants.rb"
+
+    begin
+      groups = TaxCloud::TaxCode::Groups.all.values
+      groups_and_tax_codes = Hash[groups.map do |group|
+        [ group, group.tax_codes.values ]
+      end]
+      File.open filename, "wt" do |f|
+        f.write "module TaxCloud\n"
+        f.write "  # Tax Codes.\n"
+        f.write "  class TaxCodes\n"
+        f.write "\n"
+        codes = {}
+        groups_and_tax_codes.each_pair do |group, tax_codes|
+          puts " #{group.description}"
+          f.write "    \# #{group.description}\n\n"
+          tax_codes.each do |tax_code|
+            code = tax_code.description.upcase
+            code.gsub! /[^A-Z0-9]/, '_'
+            code.gsub! /\_+$/, ''
+            code.gsub! /\_+/, '_'
+            # avoid duplicates
+            code_id = codes[code] ? "#{code}_#{codes[code]}" : code
+            codes[code] = (codes[code] || 0) + 1
+            f.write "    \# #{group.description}: #{tax_code.description}\n"
+            f.write "    #{code_id} = #{tax_code.ticid}\n"
+          end
+          f.write "\n"
+        end
+        f.write "  end\n"
+        f.write "end\n"
+      end
+      puts "Done, #{filename}."
+    rescue => e
+      puts "ERROR: Unable to generate a new list of tax codes."
+      puts e.message
+      raise e
+    end
+
+  end
+end