avatax 14.4.4 → 17.5.0

data/README.md

@@ -1,61 +1,63 @@
-avatax.rb
-=====================
-[Other Samples](http://developer.avalara.com/api-docs/api-sample-code)
-
-This is a Ruby client library for the [AvaTax REST API](http://developer.avalara.com/api-docs/rest)
-methods:
-[tax/get POST](http://developer.avalara.com/api-docs/rest/tax/post/),
-[tax/get GET](http://developer.avalara.com/api-docs/rest/tax/get),
-[tax/cancel POST](http://developer.avalara.com/api-docs/rest/tax/cancel), and
-[address/validate GET](http://developer.avalara.com/api-docs/rest/address-validation).
-
-For more information on the use of these methods and the AvaTax product, please
-visit our [developer site](http://developer.avalara.com/) or [homepage](http://www.avalara.com/)
-
-Dependencies
------------
-- Ruby 1.9.2 or later
-- [Bundler](http://bundler.io)
-
-Requirements
-----------
-- Add the `avatax` gem to your Gemfile with `gem 'avatax'`
-- Run `bundle install` to retrieve `avatax` and all its dependencies
-- Authentication requires an valid **Account Number** and **License Key**. If you do not have an AvaTax account, a free trial account can be acquired through our [developer site](http://developer.avalara.com/api-get-started)
-- Specify your authentication credentials as
-  - environment variables,
-  - YAML file (see `credentials.yml.example`), or
-  - in source
-
-Credentials as environment variables
-------------------------------------
-```shell
-$ AVATAX_ACCOUNT_NUMBER=1234567890 AVATAX_LICENSE_KEY=A1B2C3D4E5F6G7H8 AVATAX_SERVICE_URL=https://development.avalara.net bundle exec ruby examples/PingTest.rb
-```
-
-Credentials from YAML file
---------------------------
-```ruby
-AvaTax.configure_from 'credentials.yml.example'
-```
-
-Credentials in source
----------------------
-```ruby
-AvaTax.configure do
-  account_number '1234567890'
-  license_key 'A1B2C3D4E5F6G7H8'
-  service_url 'https://development.avalara.net'
-end
-```
-
-Examples
---------
-
-| Filename           | Description |
-| :----------------- | :---------- |
-| CancelTaxTest.rb   | Demonstrates [AvaTax::TaxService.cancel](http://developer.avalara.com/api-docs/rest/tax/cancel) used to [void a document](http://developer.avalara.com/api-docs/api-reference/canceltax) |
-| EstimateTaxTest.rb | Demonstrates the [AvaTax::TaxService.estimate](http://developer.avalara.com/api-docs/rest/tax/get) method used for product- and line- indifferent tax estimates. |
-| GetTaxTest.rb      | Demonstrates the [AvaTax::TaxService.get](http://developer.avalara.com/api-docs/rest/tax/post) method used for product- and line- specific [calculation](http://developer.avalara.com/api-docs/api-reference/gettax). **NOTE:** This will generate a new transaction/document each time. |
-| PingTest.rb        | Uses a hardcoded `AvaTax::TaxService.estimate` call to test connectivity and credential information. |
-| ValidateTest.rb    | Demonstrates the [AvaTax::AddressService.validate](http://developer.avalara.com/api-docs/rest/address-validation) method to [normalize an address](http://developer.avalara.com/api-docs/api-reference/address-validation). |
+The AvaTax Ruby Gem
+====================
+A Ruby wrapper for the AvaTax REST V2 APIs
+
+Installation
+------------
+	gem install avatax (coming soon)
+
+AvaTax REST and Search APIs
+------------------------------
+Our [developer site](https://developer.avalara.com/) documents all the AvaTax REST and other APIs. Subscribe to the [RSS feed](developer.avalara.com/feed.xml) to stay up to date on the lates news and announcements.
+
+
+Blog
+----------------------------
+The [Developer Blog](https://developer.avalara.com/blog/) features news and important announcements about the AvaTax Platform and SDKs. You will also find tutorials and best practices to help you build great platform integrations.
+
+Contributing
+------------
+In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), **everyone** is encouraged to help improve this project.
+
+Here are some ways *you* can contribute:
+
+* by using alpha, beta, and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace)
+* by refactoring code
+* by closing [issues](https://github.com/avadev/AvaTax-REST-V2-Ruby-SDK/issues)
+* by reviewing patches
+
+
+Submitting an Issue
+-------------------
+We use the [GitHub issue tracker](https://github.com/avadev/AvaTax-REST-V2-Ruby-SDK/issues) to track bugs and
+features. Before submitting a bug report or feature request, check to make sure it hasn't already
+been submitted. You can indicate support for an existing issue by voting it up. When submitting a
+bug report, please include a [Gist](http://gist.github.com/) that includes a stack trace and any
+details that may be necessary to reproduce the bug, including your gem version, Ruby version, and
+operating system. Ideally, a bug report should include a pull request with failing specs.
+
+Submitting a Pull Request
+-------------------------
+1. Fork the project.
+2. Create a topic branch.
+3. Implement your feature or bug fix.
+4. Add documentation for your feature or bug fix.
+5. Run <tt>rake doc:yard</tt>. If your changes are not 100% documented, go back to step 4.
+6. Add specs for your feature or bug fix.
+7. Commit and push your changes.
+8. Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)
+
+Build Status
+------------
+[![Build Status](https://travis-ci.org/avadev/AvaTax-REST-V2-Ruby-SDK.svg?branch=master)](https://travis-ci.org/avadev/AvaTax-REST-V2-Ruby-SDK)
+
+Copyright
+---------
+Copyright (c) 2017, Avalara, Inc. All rights reserved.
+By contributing to AvaTax Ruby Gem, you agree that your contributions will be licensed under its Apache License.
+See [LICENSE](https://github.com/avadev/AvaTax-REST-V2-Ruby-SDK/) for details.

data/Rakefile

@@ -0,0 +1,9 @@
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec)
+
+  task :default => :spec
+rescue LoadError
+  # no rspec available
+end

data/avatax.gemspec

@@ -0,0 +1,39 @@
+require File.expand_path('../lib/avatax/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.add_development_dependency('rake', '~> 12.0.0')
+  s.add_development_dependency('rspec', '~> 3.5.0')
+  s.add_development_dependency('webmock', '>= 2.0.0')
+  s.add_runtime_dependency('faraday', '>= 0.10')
+  s.add_runtime_dependency('faraday_middleware', '>= 0.10')
+  s.add_runtime_dependency('multi_json', '>= 1.0.3')
+  s.add_runtime_dependency('hashie', '>= 3.0.0')
+  s.authors = ["Marcus Vorwaller"]
+  s.description = %q{A Ruby wrapper for the AvaTax REST and Search APIs}
+  s.post_install_message =<<eos
+********************************************************************************
+
+AvaTax REST API
+------------------------------
+Our developer site documents the AvaTax REST API.
+(http://developer.avatax.com).
+Blog
+----------------------------
+The Developer Blog is a great place to learn more about the API and AvaTax integrations
+Subscribe to the RSS feed be notified of new posts:
+(http://developer.avatax.com/blog).
+
+********************************************************************************
+eos
+  s.email = ['marcus.vorwaller@avalara.com']
+  s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.files = `git ls-files`.split("\n")
+  s.homepage = 'https://github.com/avadev/AvaTax-REST-V2-Ruby-SDK'
+  s.name = 'avatax'
+  s.platform = Gem::Platform::RUBY
+  s.require_paths = ['lib']
+  s.required_rubygems_version = Gem::Requirement.new('>= 2.0.0') if s.respond_to? :required_rubygems_version=
+  s.summary = %q{Ruby wrapper for the AvaTax API}
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.version = AvaTax::VERSION.dup
+end

data/example/avatax.rb

@@ -0,0 +1,14 @@
+require 'yaml'
+require File.expand_path('../../lib/avatax', __FILE__)
+
+credentials = YAML.load_file(File.expand_path('../credentials.yaml', __FILE__))
+
+AvaTax.configure do |config|
+  config.endpoint = credentials['endpoint']
+  config.username = credentials['username']
+  config.password = credentials['password']
+end
+
+@client = AvaTax::Client.new(:logger => true)
+
+puts @client.query_companies

data/example/credentials.example.yaml

@@ -0,0 +1,5 @@
+# Copy this file as credentials.yaml and update the values to match your account
+---
+endpoint: https://sandbox-rest.avatax.com
+username: 'example_user'
+password: 'abcd1234'

data/lib/avatax.rb

@@ -1,20 +1,26 @@
-require_relative 'avatax/configuration'
+require File.expand_path('../avatax/configuration', __FILE__)
+require File.expand_path('../avatax/api', __FILE__)
+require File.expand_path('../avatax/client', __FILE__)
+
 module AvaTax
+  extend Configuration
+
+  # Alias for Avatax::Client.new
+  #
+  # @return [Avatax::Client]
+  def self.client(options={})
+    AvaTax::Client.new(options)
+  end
 
-  def self.configure(&block)
-    Configuration.instance.instance_eval(&block)
+  # Delegate to AvaTax::Client
+  def self.method_missing(method, *args, &block)
+    return super unless client.respond_to?(method)
+    client.send(method, *args, &block)
   end
 
-  def self.configure_from(yaml_file)
-    require 'yaml'
-    config = YAML.load_file yaml_file
-    configure do
-      account_number config['account_number']
-      license_key config['license_key']
-      service_url config['service_url']
-    end
+  # Delegate to AvaTax::Client
+  def self.respond_to?(method, include_all=false)
+    return client.respond_to?(method, include_all) || super
   end
 
 end
-require_relative 'avatax/tax_service'
-require_relative 'avatax/address_service'

data/lib/avatax/api.rb

@@ -0,0 +1,27 @@
+require File.expand_path('../connection', __FILE__)
+require File.expand_path('../request', __FILE__)
+
+module AvaTax
+  class API
+
+    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+
+    def initialize(options={})
+      options = AvaTax.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    def config
+      conf = {}
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        conf[key] = send key
+      end
+      conf
+    end
+
+    include Connection
+    include Request
+  end
+end

data/lib/avatax/client.rb

@@ -0,0 +1,32 @@
+module AvaTax
+  class Client < API
+    Dir[File.expand_path('../client/*.rb', __FILE__)].each{|f| require f}
+
+    include AvaTax::Client::Accounts
+    include AvaTax::Client::Addresses
+    include AvaTax::Client::Batches
+    include AvaTax::Client::Companies
+    include AvaTax::Client::Contacts
+    include AvaTax::Client::Definitions
+    include AvaTax::Client::FilingCalendars
+    include AvaTax::Client::Filings
+    include AvaTax::Client::Free
+    include AvaTax::Client::FundingRequests
+    include AvaTax::Client::Items
+    include AvaTax::Client::JurisdictionOverrides
+    include AvaTax::Client::Locations
+    include AvaTax::Client::Nexus
+    include AvaTax::Client::Notices
+    include AvaTax::Client::Onboarding
+    include AvaTax::Client::PointOfSale
+    include AvaTax::Client::Registrar
+    include AvaTax::Client::Settings
+    include AvaTax::Client::Subscriptions
+    include AvaTax::Client::TaxCodes
+    include AvaTax::Client::TaxRules
+    include AvaTax::Client::Transactions
+    include AvaTax::Client::Upcs
+    include AvaTax::Client::Users
+    include AvaTax::Client::Utilities
+  end
+end

data/lib/avatax/client/accounts.rb

@@ -0,0 +1,110 @@
+module AvaTax
+  class Client
+    module Accounts 
+
+
+      # Reset this account's license key
+      # 
+      # Resets the existing license key for this account to a new key.
+      # To reset your account, you must specify the ID of the account you wish to reset and confirm the action.
+      # Resetting a license key cannot be undone. Any previous license keys will immediately cease to work when a new key is created.
+      # 
+      # @param int id The ID of the account you wish to update.
+      # @param ResetLicenseKeyModel model A request confirming that you wish to reset the license key of this account.
+      # @return LicenseKeyModel
+      def account_reset_license_key(id, model)
+        path = "/api/v2/accounts/#{id}/resetlicensekey"
+        
+        post(path, model)
+      end
+
+
+      # Activate an account by accepting terms and conditions
+      # 
+      # Activate the account specified by the unique accountId number.
+      # 
+      # This activation request can only be called by account administrators. You must indicate 
+      # that you have read and accepted Avalara's terms and conditions to call this API.
+      # 
+      # If you have not read or accepted the terms and conditions, this API call will return the
+      # unchanged account model.
+      # 
+      # @param int id The ID of the account to activate
+      # @param ActivateAccountModel model The activation request
+      # @return AccountModel
+      def activate_account(id, model)
+        path = "/api/v2/accounts/#{id}/activate"
+        
+        post(path, model)
+      end
+
+
+      # Retrieve a single account
+      # 
+      # Get the account object identified by this URL.
+      # You may use the '$include' parameter to fetch additional nested data:
+      # 
+      # * Subscriptions
+      # * Users
+      # 
+      # @param int id The ID of the account to retrieve
+      # @param string include A comma separated list of child objects to return underneath the primary object.
+      # @return AccountModel
+      def get_account(id, options={})
+        path = "/api/v2/accounts/#{id}"
+        
+        get(path, options)
+      end
+
+
+      # Get configuration settings for this account
+      # 
+      # Retrieve a list of all configuration settings tied to this account.
+      # 
+      # Configuration settings provide you with the ability to control features of your account and of your
+      # tax software. The category names `TaxServiceConfig` and `AddressServiceConfig` are reserved for
+      # Avalara internal software configuration values; to store your own account-level settings, please
+      # create a new category name that begins with `X-`, for example, `X-MyCustomCategory`.
+      # 
+      # Account settings are permanent settings that cannot be deleted. You can set the value of an
+      # account setting to null if desired.
+      # 
+      # Avalara-based account settings for `TaxServiceConfig` and `AddressServiceConfig` affect your account's
+      # tax calculation and address resolution, and should only be changed with care.
+      # 
+      # @param int id 
+      # @return AccountConfigurationModel[]
+      def get_account_configuration(id)
+        path = "/api/v2/accounts/#{id}/configuration"
+        
+        get(path)
+      end
+
+
+      # Change configuration settings for this account
+      # 
+      # Update configuration settings tied to this account.
+      # 
+      # Configuration settings provide you with the ability to control features of your account and of your
+      # tax software. The category names `TaxServiceConfig` and `AddressServiceConfig` are reserved for
+      # Avalara internal software configuration values; to store your own account-level settings, please
+      # create a new category name that begins with `X-`, for example, `X-MyCustomCategory`.
+      # 
+      # Account settings are permanent settings that cannot be deleted. You can set the value of an
+      # account setting to null if desired.
+      # 
+      # Avalara-based account settings for `TaxServiceConfig` and `AddressServiceConfig` affect your account's
+      # tax calculation and address resolution, and should only be changed with care.
+      # 
+      # @param int id 
+      # @param AccountConfigurationModel[] model 
+      # @return AccountConfigurationModel[]
+      def set_account_configuration(id, model)
+        path = "/api/v2/accounts/#{id}/configuration"
+        
+        post(path, model)
+      end
+
+    end
+  end
+end

data/lib/avatax/client/addresses.rb

@@ -0,0 +1,52 @@
+module AvaTax
+  class Client
+    module Addresses 
+
+
+      # Retrieve geolocation information for a specified address
+      # 
+      # Resolve an address against Avalara's address-validation system. If the address can be resolved, this API 
+      # provides the latitude and longitude of the resolved location. The value 'resolutionQuality' can be used 
+      # to identify how closely this address can be located. If the address cannot be clearly located, use the 
+      # 'messages' structure to learn more about problems with this address.
+      # This is the same API as the POST /api/v2/addresses/resolve endpoint.
+      # Both verbs are supported to provide for flexible implementation.
+      # 
+      # @param string line1 Line 1
+      # @param string line2 Line 2
+      # @param string line3 Line 3
+      # @param string city City
+      # @param string region State / Province / Region
+      # @param string postalCode Postal Code / Zip Code
+      # @param string country Two character ISO 3166 Country Code (see /api/v2/definitions/countries for a full list)
+      # @param string textCase selectable text case for address validation (See TextCase::* for a list of allowable values)
+      # @param float latitude Geospatial latitude measurement
+      # @param float longitude Geospatial longitude measurement
+      # @return AddressResolutionModel
+      def resolve_address(options={})
+        path = "/api/v2/addresses/resolve"
+        
+        get(path, options)
+      end
+
+
+      # Retrieve geolocation information for a specified address
+      # 
+      # Resolve an address against Avalara's address-validation system. If the address can be resolved, this API 
+      # provides the latitude and longitude of the resolved location. The value 'resolutionQuality' can be used 
+      # to identify how closely this address can be located. If the address cannot be clearly located, use the 
+      # 'messages' structure to learn more about problems with this address.
+      # This is the same API as the GET /api/v2/addresses/resolve endpoint.
+      # Both verbs are supported to provide for flexible implementation.
+      # 
+      # @param AddressValidationInfo model The address to resolve
+      # @return AddressResolutionModel
+      def resolve_address_post(model)
+        path = "/api/v2/addresses/resolve"
+        
+        post(path, model)
+      end
+
+    end
+  end
+end