super_good-solidus_taxjar 0.18.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 977d3ededff1e9bd56c37b6dda9228545160525fed6f7667e194e0ab45486ce8
-  data.tar.gz: 10466dec877f8de3eadb843929ec93173bc30fd7ab58be34c5ff08d5de4214b2
+  metadata.gz: 1ea462e3495029115fadb24132bdd24c82eb099c69e54864f51958b2df7986ee
+  data.tar.gz: c90b8d81ddd5d173b6bd62b276e7a7f472f2f90018ab3568e2ae82dcd4e21f88
 SHA512:
-  metadata.gz: 46ffc2f0a1c52205acdf91a12ec2a3b1806bca174450a1a763e03ba1c54add5a7c82ac538b04bca72c31fa7d295fc2cd9a040e719cd58ddaf7233a1af7655b35
-  data.tar.gz: 3186b598fb5d11dd0cab75e145d8e088e6563562767acab012e4127544428fa6e4ac927adb2cc1c9ccbd7dfc831e7bdde1e402462596230736045bb970d54c6e
+  metadata.gz: dada93cad3b627f3b76fe73825a62831c38f583dd695e4de42d869e3bbcb23143097509167f6eb6298fdc46b8a85f1fca7dc4bfdb1e22ab19337a6ab7e76c0a9
+  data.tar.gz: a9e0be635741a3c9e4dc2b02cd9588f493db59c3bee25a2331513f40ecdc6b1662618bd7440f5b7227410d03b14701325c775f138645b75da147380933fdb80b

data/.circleci/config.yml

@@ -0,0 +1,58 @@
+version: 2.1
+orbs:
+  # Browser tools are required for feature specs.
+  browser-tools: circleci/browser-tools@1.4
+
+  # Always run tests agains the versions of Solidus defined in the
+  # most recent version of the Orb.
+  solidusio_extensions: solidusio/extensions@volatile
+
+jobs:
+  run-specs-solidus-current:
+    executor:
+      name: solidusio_extensions/postgres
+      ruby_version: "3.0"
+    steps:
+      - checkout
+      - browser-tools/install-browser-tools
+      - solidusio_extensions/run-tests-solidus-older
+      - solidusio_extensions/run-tests-solidus-current
+      - solidusio_extensions/store-test-results
+  run-specs-solidus-older:
+    executor:
+      name: solidusio_extensions/postgres
+      ruby_version: "3.0"
+    steps:
+      - checkout
+      - browser-tools/install-browser-tools
+      - solidusio_extensions/run-tests-solidus-older
+      - solidusio_extensions/store-test-results
+  run-specs-solidus-main:
+    executor:
+      name: solidusio_extensions/postgres
+      ruby_version: "3.1"
+    steps:
+      - browser-tools/install-browser-tools
+      - checkout
+      - solidusio_extensions/run-tests-solidus-main
+      - solidusio_extensions/store-test-results
+workflows:
+  "Run specs on current Solidus versions":
+    jobs:
+      - run-specs-solidus-current
+  "Run specs on older Solidus versions":
+    jobs:
+      - run-specs-solidus-older
+  "Run specs on Solidus main":
+    jobs:
+      - run-specs-solidus-main
+  "Weekly run specs against master":
+    triggers:
+      - schedule:
+          cron: "0 0 * * 4" # every Thursday
+          filters:
+            branches:
+              only:
+                - master
+    jobs:
+      - run-specs-solidus-main

data/CHANGELOG.md

@@ -1,15 +1,128 @@
 # Changelog
-
-## master
-
-## v0.18.1 
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+- Nothing yet.
+
+## v1.0.0
+
+### Added
+
+- [#190](https://github.com/SuperGoodSoft/solidus_taxjar/pull/190) Add transaction sync batch show page
+- [#188](https://github.com/SuperGoodSoft/solidus_taxjar/pull/188) Show transaction sync batches in user interface
+- [#185](https://github.com/SuperGoodSoft/solidus_taxjar/pull/185) Backfill transactions in batches
+- [#139](https://github.com/SuperGoodSoft/solidus_taxjar/pull/139) Refund and create a new order transaction when an order is recalculated
+- [#175](https://github.com/SuperGoodSoft/solidus_taxjar/pull/175) Add request logging to TaxJar API requests
+- [#138](https://github.com/SuperGoodSoft/solidus_taxjar/pull/138) Add admin UI for configuring reporting
+- [#158](https://github.com/SuperGoodSoft/solidus_taxjar/pull/158) Update sandbox bin stub for `solidus@3`
+- [#88](https://github.com/SuperGoodSoft/solidus_taxjar/pull/88) Fire `shipment_shipped` event when any shipment on an order ships.
+- [#81](https://github.com/SuperGoodSoft/solidus_taxjar/pull/81) Add install generator
+- [#98](https://github.com/SuperGoodSoft/solidus_taxjar/pull/98) Add generator for TaxJar transaction IDs
+- [#103](https://github.com/SuperGoodSoft/solidus_taxjar/pull/103) Add `reporting_enabled` configuration option
+- [#97](https://github.com/SuperGoodSoft/solidus_taxjar/pull/97) Add public API method to request the latest transaction associated with a solidus order.
+- [#100](https://github.com/SuperGoodSoft/solidus_taxjar/pull/100) Add public API method to post a taxjar refund transaction for a solidus order.
+- [#102](https://github.com/SuperGoodSoft/solidus_taxjar/pull/102) Add description to transaction line item params
+- [#108](https://github.com/SuperGoodSoft/solidus_taxjar/pull/108) Add new model associated with a `Spree::Order` to represent taxjar order creation transactions
+- [#114](https://github.com/SuperGoodSoft/solidus_taxjar/pull/114) Add new model associated with a `SuperGood::SolidusTaxjar::OrderTransaction` to represent taxjar refund creation transactions
+- [#116](https://github.com/SuperGoodSoft/solidus_taxjar/pull/116) Update the `OrderTransaction` model to record the transaction date.
+- [#109](https://github.com/SuperGoodSoft/solidus_taxjar/pull/109) Save `OrderTransaction` after API call to TaxJar
+- [#111](https://github.com/SuperGoodSoft/solidus_taxjar/pull/111) Create a new taxjar transaction when a shipment is shipped.
+- [#141](https://github.com/SuperGoodSoft/solidus_taxjar/pull/141) Handle unimplemented reporting features
+- [#129](https://github.com/SuperGoodSoft/solidus_taxjar/pull/129) Report transaction asynchronously when a shipment is shipped.
+- [#127](https://github.com/SuperGoodSoft/solidus_taxjar/pull/127) Add acceptance test for calculating taxes with the extension.
+- [#160](https://github.com/SuperGoodSoft/solidus_taxjar/pull/160) Add tax categories API endpoint wrapper
+- [#171](https://github.com/SuperGoodSoft/solidus_taxjar/pull/171) Display existing Nexus regions
+- [#170](https://github.com/SuperGoodSoft/solidus_taxjar/pull/170) Hide all reporting features behind API key
+- [#174](https://github.com/SuperGoodSoft/solidus_taxjar/pull/174) Provide a link to Taxjar state settings
+- [#177](https://github.com/SuperGoodSoft/solidus_taxjar/pull/177) Make nexus caching configurable
+- [#169](https://github.com/SuperGoodSoft/solidus_taxjar/pull/169) Add basic backfill transaction functionality
+- [#176](https://github.com/SuperGoodSoft/solidus_taxjar/pull/176) Create refund transaction database models when reporting refunds.
+- [#192](https://github.com/SuperGoodSoft/solidus_taxjar/pull/192) Handle failures that occur in the middle of refunding a transaction.
+- [#194](https://github.com/SuperGoodSoft/solidus_taxjar/pull/194) Move the transaction backfill button to it's own unique page
+- [#198](https://github.com/SuperGoodSoft/solidus_taxjar/pull/198) Don't create zero dollar transactions when an order is fully refunded.
+- [#195](https://github.com/SuperGoodSoft/solidus_taxjar/pull/195) Run transaction backfills asynchronously
+- [#200](https://github.com/SuperGoodSoft/solidus_taxjar/pull/200) Expand `solidus` gem into dependencies to support Solidus 3.2+
+- [#183](https://github.com/SuperGoodSoft/solidus_taxjar/pull/183) Add ability to fetch tax codes from TaxJar and assign to tax categories in admin
+- [#200](https://github.com/SuperGoodSoft/solidus_taxjar/pull/200) Render error message when backfilling transactions fails
+- [#203](https://github.com/SuperGoodSoft/solidus_taxjar/pull/203) Remove outdated backfill button
+- [#202](https://github.com/SuperGoodSoft/solidus_taxjar/pull/202) Add TaxJar transaction sync status to order show page
+- [#204](https://github.com/SuperGoodSoft/solidus_taxjar/pull/204) Add page to render an orders TaxJar transactions
+- [#201](https://github.com/SuperGoodSoft/solidus_taxjar/pull/201) Allow transaction backfills to be filtered by date range
+- [#244](https://github.com/SuperGoodSoft/solidus_taxjar/pull/244) Let admins manually retry syncing failed TaxJar transactions
+- [#255](https://github.com/SuperGoodSoft/solidus_taxjar/pull/255) Add a delay before reporting transactions
+- [#253](https://github.com/SuperGoodSoft/solidus_taxjar/pull/253) Fix various bugs with reporting refund transactions
+
+### Changed
+
+- [#95](https://github.com/SuperGoodSoft/solidus_taxjar/pull/95) Only require "state" for Canadian and US addresses
+- [#181](https://github.com/SuperGoodSoft/solidus_taxjar/pull/181) Take all non-tax adjustment types into account when calculating a line item's discount
+- [#182](https://github.com/SuperGoodSoft/solidus_taxjar/pull/182) Automatically create default Tax Rate
+- [#205](https://github.com/SuperGoodSoft/solidus_taxjar/pull/205) Use nexus regions for taxable address checks
+- [#218](https://github.com/SuperGoodSoft/solidus_taxjar/pull/218) Removed `order_recalculated` event backport
+- [#216](https://github.com/SuperGoodSoft/solidus_taxjar/pull/216) Add `deface` as a dependency.
+- [#217](https://github.com/SuperGoodSoft/solidus_taxjar/pull/217) Handle updates to orders that have not been reported
+- [#227](https://github.com/SuperGoodSoft/solidus_taxjar/pull/227) Fix reporting for orders with refunds
+- [#226](https://github.com/SuperGoodSoft/solidus_taxjar/pull/226) Refactor reporting subscriber logic
+- [#238](https://github.com/SuperGoodSoft/solidus_taxjar/pull/238) Drop support for loading of reporting subscriber for Solidus < 2.11
+- [#237](https://github.com/SuperGoodSoft/solidus_taxjar/pull/237) Sort order transactions by `created_at`
+- [#236](https://github.com/SuperGoodSoft/solidus_taxjar/pull/236) Don't send cancelled or returned line items
+- [#225](https://github.com/SuperGoodSoft/solidus_taxjar/pull/225) Create sync logs for replace transaction jobs
+- [#231](https://github.com/SuperGoodSoft/solidus_taxjar/pull/231) Load Solidus factories using new conventions
+- [#246](https://github.com/SuperGoodSoft/solidus_taxjar/pull/246) Fix bugs with sync retries when reporting or replacing a transaction fails
+
+### Removed
+
+- [#137](https://github.com/SuperGoodSoft/solidus_taxjar/pull/137) Only run tests against Solidus 2.11. This also represents the drop of official support for Solidus 2.9 and 2.10.
+- [#193](https://github.com/SuperGoodSoft/solidus_taxjar/pull/193) Bump version requirement for `solidus_support` to ">= 0.9.0", and as a result drop support for Rails 5.2.
+
+### Fixed
+
+- [#107](https://github.com/SuperGoodSoft/solidus_taxjar/pull/107) Fix rails-engine binstub to point to correct engine entry point
+- [#117](https://github.com/SuperGoodSoft/solidus_taxjar/pull/117) Fix migration install
+- [#119](https://github.com/SuperGoodSoft/solidus_taxjar/pull/119) Move the install generator into the correct path so that it will be installed in the dummy app.
+- [#250](https://github.com/SuperGoodSoft/solidus_taxjar/pull/250) Improve error handling for `ReportTransactionJob`
+- [#254](https://github.com/SuperGoodSoft/solidus_taxjar/pull/254) Get tests and binstubs working against Solidus `main`
+
+### Development Changes
+
+These changes only affect the development of this extension.
+
+- [#120](https://github.com/SuperGoodSoft/solidus_taxjar/pull/120) Change default `SOLIDUS_BRANCH` and `RAILS_VERSION`
+- [#137](https://github.com/SuperGoodSoft/solidus_taxjar/pull/137) Run tests against the most up to date versions of Solidus
+- [#249](https://github.com/SuperGoodSoft/solidus_taxjar/pull/249) Don't depend on `webdrivers` gem
+
+### Upgrading from 0.18.x to 1.0.0
+
+If you had previously configured a `Spree::TaxRate` with the name "Sales Tax",
+it can be deleted after upgrading, as a new `Spree::TaxRate` with the name
+"Solidus TaxJar Rate" will automatically be created. Alternatively, you can
+rename your existing `Spree::TaxRate` from "Sales Tax" to "Solidus TaxJar
+Rate". [#182](https://github.com/SuperGoodSoft/solidus_taxjar/pull/182)
+
+## v0.18.2
+
+- [#71](https://github.com/SuperGoodSoft/solidus_taxjar/pull/69) Unlock ExecJS version. This reverts the temporary fix introduced in #69
+- [#79](https://github.com/SuperGoodSoft/solidus_taxjar/pull/79) Relax Ruby required version to support Ruby 3.0+
+- [#51](https://github.com/SuperGoodSoft/solidus_taxjar/pull/51) Add nexus regions method to API
+- [#58](https://github.com/SuperGoodSoft/solidus_taxjar/pull/58) Take shipping promotions into account in default calculator
+- [#59](https://github.com/SuperGoodSoft/solidus_taxjar/pull/59) Add pry debugging tools
+- [#69](https://github.com/SuperGoodSoft/solidus_taxjar/pull/69) Lock ExecJS version
+- [#37](https://github.com/SuperGoodSoft/solidus_taxjar/pull/37) Added a basic Taxjar settings admin interface which displays placeholder text.
+- [#64](https://github.com/SuperGoodSoft/solidus_taxjar/pull/64) Provide Spree::Address.address2 to TaxJar address validation if it is present.
+- [#80](https://github.com/SuperGoodSoft/solidus_taxjar/pull/80) Support order_recalculated event in < 2.11
+
+## v0.18.1
 
 [#52](https://github.com/supergoodsoft/solidus_taxjar/pull/52) fixes a critical bug in the API class that was released in `v0.18.0`. Please upgrade.
 
 - [#47](https://github.com/SuperGoodSoft/solidus_taxjar/pull/47) Fixed bug in `validate_address_params` for addresses without a state
 - [#52](https://github.com/supergoodsoft/solidus_taxjar/pull/52) Fixed critical bug in API class
 
-## ~~v0.18.0~~ 
+## ~~v0.18.0~~
 `v0.18.0` was removed due to a regression in the API class that was fixed in [#52](https://github.com/SuperGoodSoft/solidus_taxjar/pull/52) and `v0.18.1`
 
 - [#21](https://github.com/SuperGoodSoft/solidus_taxjar/pull/21) Migrated project to `solidus_dev_support`

data/Gemfile

@@ -1,16 +1,25 @@
-source "https://rubygems.org"
-
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+# frozen_string_literal: true
 
-branch = ENV.fetch('SOLIDUS_BRANCH', 'master')
-
-gem "solidus", github: "solidusio/solidus", branch: branch
+source "https://rubygems.org"
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+branch = ENV.fetch("SOLIDUS_BRANCH", "v3.1")
+git "https://github.com/solidusio/solidus.git", branch: branch do
+  gem "solidus_core"
+  gem "solidus_backend"
+  gem "solidus_api"
+  gem "solidus_sample"
+end
 
-# Needed to help Bundler figure out how to resolve dependencies,
-# otherwise it takes forever to resolve them.
-# See https://github.com/bundler/bundler/issues/6677
-gem "rails", ENV.fetch("RAILS_VERSION") { ">0.a" }
+if (branch == 'main') || (branch >= 'v4.0')
+  gem "solidus_frontend", github: "solidusio/solidus_frontend", branch: 'main'
+elsif (branch >= 'v3.2') && (branch < 'v4.0')
+  gem "solidus_frontend", github: "solidusio/solidus_frontend", branch: branch
+else
+  gem "solidus_frontend", github: "solidusio/solidus", branch: branch
+end
 
+gem "rails"
 # Provides basic authentication functionality for testing parts of your engine
 gem "solidus_auth_devise"
 
@@ -25,6 +34,15 @@ end
 
 group :development, :test do
   gem "pry"
+  gem "pry-stack_explorer"
+  gem "pry-byebug"
+
+  # FIXME:
+  # Once a new version of `solidus_dev_support` is released to RubyGems, we can
+  # use that.
+  gem "solidus_dev_support",
+    github: "solidusio/solidus_dev_support",
+    branch: "main"
 end
 
 gemspec

data/README.md

@@ -1,91 +1,346 @@
-# `SuperGood::SolidusTaxjar` [![Build Status](https://travis-ci.com/SuperGoodSoft/solidus_taxjar.svg?token=rc5QTgHvLLF7cpqkmyfd&branch=master)](https://travis-ci.com/SuperGoodSoft/solidus_taxjar)
+# `SuperGood::SolidusTaxjar`
 
-`SuperGood::SolidusTaxjar` is a [Solidus](https://github.com/solidusio/solidus) extension that allows Solidus stores to use [TaxJar](https://www.taxjar.com/) for tax calculations.
+[![CircleCI build status](https://circleci.com/gh/SuperGoodSoft/solidus_taxjar/tree/master.svg?style=shield)](https://circleci.com/gh/SuperGoodSoft/solidus_taxjar/tree/master)
 
-This is not a fork of [spree_taxjar](https://github.com/vinsol-spree-contrib/spree_taxjar), like [solidus_taxjar](https://github.com/boomerdigital/solidus_taxjar). Instead of using a custom calculator, `SuperGood::SolidusTaxjar` uses the new configurable tax system [by @adammathys](https://github.com/solidusio/solidus/pull/1892) introduced in Solidus v2.4. This maps better to how the TaxJar API itself works.
+`SuperGood::SolidusTaxjar` is a [Solidus](https://github.com/solidusio/solidus)
+extension that allows Solidus stores to use [TaxJar](https://www.taxjar.com/)
+for tax calculations.
 
-## Installation
+This is not a fork of [`spree_taxjar`][spree_taxjar] like Boomer Digital's
+[`solidus_taxjar`][boomer_taxjar] extension. Instead of using a custom
+calculator, `SuperGood::SolidusTaxjar` uses the new configurable tax system [by
+@adammathys](https://github.com/solidusio/solidus/pull/1892) introduced in
+Solidus v2.4. This maps better to how the TaxJar API itself works.
 
-1. Add this line to your application's Gemfile:
+[boomer_taxjar]: https://github.com/boomerdigital/solidus_taxjar
+[spree_taxjar]: https://github.com/vinsol-spree-contrib/spree_taxjar
+
+## Documentation
+
+**If you're a developer**, any information you need about this Solidus extension
+should be referenced in this file or in the source code of the extension.
+
+**If you're not a developer**, see [the wiki][wiki] for additional documentation
+about using the Solidus TaxJar extension after it has been installed.
 
-   ```ruby
-   gem 'super_good-solidus_taxjar'
-   ```
+[wiki]: https://github.com/supergoodsoft/solidus_taxjar/wiki
 
-   And then execute:
+## Installation
+
+1. Add this line to your application's Gemfile:
 
-       $ bundle
+    ```ruby
+    gem 'super_good-solidus_taxjar'
+    ```
 
-2. Install and run the necessary migrations:
+    And then execute:
 
-   ```shell
-   bundle exec rails g super_good:solidus_taxjar:install
-   bundle exec rake db:migrate
-   ```
+    ```sh
+    bundle
+    ```
 
-3. Next, configure Solidus to use this gem:
+2. Next, configure Solidus to use this gem by running the install generator:
 
-   ```ruby
-   # Put this in config/initializers/solidus.rb
+    ```sh
+    bundle exec rails generate super_good:solidus_taxjar:install
+    ```
 
-   Spree.config do |config|
-     config.tax_calculator_class = SuperGood::SolidusTaxjar::TaxCalculator
-   end
-   ```
+3. Also, configure your own [exception handler](#exception-handling).
 
-4. Also, configure your error handling:
+4. Finally, make sure that the `TAXJAR_API_KEY` environment variable is set to
+   your TaxJar API key.
 
-   ```ruby
-   # Put this in config/initializers/taxjar.rb
+### Warning: Installing on Production
 
-   SuperGood::SolidusTaxjar.exception_handler = ->(e) {
-     # Report exceptions in here. For example, if you were using the Sentry's
-     # raven-ruby gem to report errors, you might do this:
-     Raven.capture_exception(e)
-   }
-   ```
+Before you install this extension in your production environment, **we strongly
+recommend that you install and configure a supported ActiveJob backend**.
 
-5. Finally, make sure that the `TAXJAR_API_KEY` environment variable is set to a your TaxJar API key and make sure that you have a `Spree::TaxRate` with the name "Sales Tax". This will be used as the source for the tax adjustments that Solidus creates.
+By default, ActiveJob performs jobs in memory. The order reporting backfill
+functionality of this extension may enqueue *a lot* of jobs if you have hundreds
+or thousands of historical orders to report.
 
-## Project Status
+Using this extension without a backend like Sidekiq, Resque, or Delayed Job,
+**may cause your application to crash with out-of-memory errors**. For more
+information, read the Rails Guides's [Active Jobs Basics][active-job-basics]
+article. You may find the [Job Execution][active-job-execution] section
+particularly helpful.
 
-This extension is under active development and not yet at a v1.0 release, but it's currently being used in production by multiple Solidus stores.
+[active-job-basics]: https://edgeguides.rubyonrails.org/active_job_basics.html
+[active-job-execution]: https://edgeguides.rubyonrails.org/active_job_basics.html#job-execution
 
-Requirements for TaxJar integrations vary as some stores also need reporting, which isn't provided out of the box by this extension. This is because individual stores will be using different background job frameworks or runners (Sidekiq, delayed_job, ActiveJob, etc.) and a reliable integration will rely on one of these. Because this part of the integration is small, we've chosen to provide the transaction reporting functionality, but have skipped directly integrating it.
+## Developer Support
 
-If you're having trouble integrating this extension with your store and would like some assistance, please reach out to Jared via e-mail at [jared@super.gd](mailto:jared@super.gd) or on the official Solidus as `@jared`.
+If you're having trouble integrating this extension with your store and would
+like some assistance, please reach out to Jared via e-mail at [jared@super.gd](mailto:jared@super.gd)
+or on the official Solidus Slack as `@Jared Norman`.
 
 ## Features
 
-The extension provides currently two high level `calculator` classes that wrap the low-level Ruby taxjar gem API calls:
+This extension provides two high level `calculator` classes that wrap the
+low-level Ruby `taxjar` gem API calls:
 
 * tax calculator
 * tax rate calculator
 
+:warning: The transaction reporting features this extension provides depend on
+the Solidus event system, and in particular the `order_recalculated` event.
+That does not exist on Solidus < 2.11, so if you're version of Solidus is older
+than that and you want to use the reporting feature you will need to backport
+that event to your applicaiton.
+
+This extension also supports:
+
+* syncing orders to TaxJar's reporting dashboard
+* syncing nexus regions as configured in the connected TaxJar account (including
+  automatic _and_ manual sync)
+* connecting your Solidus store's tax categories to TaxJar's tax categories (U.S. tax codes)
+
+**Note that reporting is turned off by default.**
+
 ### TaxCalculator
 
-`SuperGood::SolidusTaxjar::TaxCalculator` allows calculating the full tax breakdown for a given `Spree::Order`. The breakdown includes separate line items taxes and shipment taxes.
+`SuperGood::SolidusTaxjar::TaxCalculator` allows calculating the full tax
+breakdown for a given `Spree::Order`. The breakdown includes separate line items
+taxes and shipment taxes.
+
+This tax calculator will create a `Spree::TaxRate` that is required for tax
+adjustments. All other `Spree::TaxRate`s will be ignored in calculations. See
+[this wiki
+page](https://github.com/SuperGoodSoft/solidus_taxjar/wiki/How-Solidus-TaxJar-calculates-tax)
+for more details.
 
 ### TaxRateCalculator
 
-`SuperGood::SolidusTaxjar::TaxRateCalculator` allows calculating the tax rate for a given `Spree::Address`. It relies on the same low-level Ruby TaxJar API endpoint of the tax calculator in order to provide the most coherent and reliable results. TaxJar support recommends using this endpoint for live calculations.
+`SuperGood::SolidusTaxjar::TaxRateCalculator` allows calculating the tax rate
+for a given `Spree::Address`. It relies on the same low-level Ruby TaxJar API
+endpoint of the tax calculator in order to provide the most coherent and
+reliable results. TaxJar support recommends using this endpoint for live
+calculations.
+
+### Order-level Adjustments are Unsupported
+
+Although Solidus supports order-level adjustments, **TaxJar does not support
+order-level adjustments**. Currently, this extension does not make any
+assumptions about how order-level adjustments should be reported to TaxJar.
+After enabling the extension, any attempts to create an order-level adjustment
+will result in an error being raised by default.
+
+**If you need to support order-level adjustments, you'll need to configure the
+`discount_calculator` setting to handle them.** See
+[Configuration](#configuration) for more more information about configuring the
+extension.
+
+## Configuration
+
+Developers can configure the extension in a Rails initializer file. All of the
+configuration settings, and their default values, are defined in
+[`lib/super_good/solidus_taxjar.rb`](lib/super_good/solidus_taxjar.rb). The
+settings are described in the [Settings](#settings) section below.
+
+As an example, your application's initializer might look like this:
+
+```ruby
+# config/initializers/taxjar.rb
+
+SuperGood::SolidusTaxjar.tap do |config|
+  config.cache_duration = 2.hours
+  config.line_item_tax_label_maker = ->(taxjar_line_item, spree_line_item) {
+    "My Tax Label"
+  }
+  config.test_mode = true
+end
+```
+
+### Settings
+
+Developers can configure the following settings in an initializer:
+
+- `cache_duration`: The length of time that cacheable responses from
+  the TaxJar API are cached. Cacheable responses include the list of active
+  nexus regions, as well as tax and tax rate calculations.
+
+  Default value: `3.hours`
+
+- `cache_key`:  function that returns a distinct cache key for
+  a cacheable response from the TaxJar API. A safe default function is provided.
+
+  Default value: (See the source code.)
+
+- `custom_order_params`: A function that returns any parameterized custom
+	order information you need to send to TaxJar in every API request that
+	includes a customer's order. By default no custom order parameters are
+	sent.
+
+	Note that all the essential `Spree::Order`, `Spree::LineItem`, and
+	`Spree::Address` attributes are already sent by default.
+
+	Default value: `{}`
+
+- `discount_calculator`: A discount calculator class. A safe default
+  calculator is provided: it handles promotions that rely on line item and
+  shipment adjustments. Since TaxJar requires dicounts to be specified per line
+  item, you need to provide a custom version of this calculator in order to
+  support any of your promotions that create order-level adjustments.
+
+  Default value: `::SuperGood::SolidusTaxjar::DiscountCalculator`
+
+- `exception_handler`: A function that returns your own exception
+  handler. See [Exception handling](#exception-handling).
+
+  Default value: (See the source code.)
+
+- `job_queue`: A string or symbol that matches the name of a job queue in your
+  application's job queuer. (The extension uses ActiveJob to delegate new jobs.)
+
+	Default value: `:default`
+
+- `line_item_tax_label_maker`: A string to label line item taxes in TaxJar.
+
+  Default value: "Sales Tax"
+
+- `logging_enabled`: Boolean. Whether logging is enabled.
+
+  Default value: `true`
+
+- `shipping_calculator`: A function that calculates the total cost of the
+  shipments for an order. A default default is provided
+  inline, but your store may require additional logic
+  for accurate calculations.
+
+  Default value: (See the source code.)
+
+- `shipping_tax_label_maker`: A string to label shipment taxes in TaxJar.
+
+  Default value: "Sales Tax"
+
+- `taxable_address_check`: A function that returns a boolean after checking
+  whether an address should be considered taxable. By default this function
+  returns `true`.
+
+  Default value: `true`
+
+- `taxable_order_check`: A function that returns a boolean after checking
+  whether an order should be considered taxable.  By default this function
+  always returns `true`.
+
+  Default value: `true`
+
+- `test_mode`: Boolean. Whether the extension is in test mode.
+  If true, no tax or tax rate calculations will be requested via the TaxJar API.
+
+  Default value: `false`
+
+### Taxable Orders
+
+Note that the configuration setting `taxable_order_check` can be customized if
+there is specific criteria that make some orders taxable and other orders not
+taxable. By default this extension considers all orders taxable.
+
+### Exception Handling
+
+You can configure your own exception handler in an initializer. using the
+`exception_handler` configuration point:
+
+```ruby
+# Put this in config/initializers/taxjar.rb
+
+SuperGood::SolidusTaxjar.exception_handler = ->(e) {
+  # Report exceptions in here. For example, if you were using the Sentry's
+  # raven-ruby gem to report errors, you might do this:
+  Raven.capture_exception(e)
+}
+```
+
+For more information about configuring the extension, see
+[Configuration](#configuration).
+
+### Logging
+
+By default, all requests to TaxJar are logged to the Rails logger. URIs, HTTP
+method, and response codes will be logged at the `info` level, any further
+details (such as response body) are logged at the `debug` level.
+
+If you are interested in logs for full request responses, be sure to set your
+logger to the `debug` level:
+
+```ruby
+Rails.logger.level = 0 # debug
+```
+
+Or, if you want an alternate logger implementation, you can provide your own:
+
+```ruby
+SuperGood::SolidusTaxjar.tap do |config|
+  logger = Logger.new(STDOUT)
+  logger.log_level = :warn
+  config.logger = logger
+end
+```
+
+More details on the Rails Logger are available [here](https://guides.rubyonrails.org/debugging_rails_applications.html#the-logger).
+
+Logging can also be disabled all together:
+
+```ruby
+SuperGood::SolidusTaxjar.tap do |config|
+  config.logging_enabled = false
+end
+```
 
 ## Development
 
-Before installing dependencies, make sure your environment variables are setup. Our CI uses something like this: `SOLIDUS_BRANCH=v2.10 DB=postgresql RAILS_VERSION="~> 5.2.0`. These environment variables need to be set when installing dependencies and running specs, so set them before the command like this: `SOLIDUS_BRANCH=v2.10 DB=postgresql RAILS_VERSION="~> 5.2.0 bin/setup`
+Run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the
+tests. You can also run `bin/console` for an interactive prompt that will allow
+you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Changing the Rails/Solidus Versions
+
+The Rails and the Solidus version can be changed by setting the `RAILS_VERSION`
+and `SOLIDUS_BRANCH` environment variables, respectively. See the
+[Gemfile](./Gemfile) for examples.
+
+### Changing the Database Vendor
+
+The database vendor can also be changed from the default (`sqlite3`) by setting
+the `DB` environment variable.
+
+### Testing the Extension
+
+When testing your application's integration with this extension you may use its factories.
+You can load Solidus core factories along with this extension's factories using this statement:
+
+```ruby
+SolidusDevSupport::TestingSupport::Factories.load_for(SuperGoodSolidusTaxjar::Engine)
+```
 
-Run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## Releasing a New Version
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+1. Update the `master` header in changelog to the version that you're releasing.
+2. Commit your changes and open a PR for the release
+3. Once the PR has been merged into master, run `gem bump -v [<major>|<minor>|<patch>] -p -t -r` to create a tag and release the gem to ✨ RubyGems ✨
+4. Push your local master branch with `--tags` to the repository to add the tag to github.
+5. Create a new release on github with the tag
+    * [ ] Ensure the changelog since the previous release is included
+    * [ ] Ensure you have noted version migration instructions if applicable
+    * [ ] Ensure breaking/significant changes are clearly highlighted
+    * [ ] Ensure changes that are **not production ready** are clearly highlighted
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/SuperGoodSoft/solidus_taxjar. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at [https://github.com/SuperGoodSoft/solidus_taxjar](https://github.com/SuperGoodSoft/solidus_taxjar).
+This project is intended to be a safe, welcoming space for collaboration, and
+contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org)
+code of conduct.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the `SuperGood::SolidusTaxjar` project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/SuperGoodSoft/solidus_taxjar/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the `SuperGood::SolidusTaxjar` project’s codebases,
+issue trackers, chat rooms and mailing lists is expected to follow the
+[code of conduct](https://github.com/SuperGoodSoft/solidus_taxjar/blob/master/CODE_OF_CONDUCT.md).