jwietelmann / jar

An API client for TaxJar in Elixir.

Jar

An example TaxJar API client.

Usage

Jar can be configured globally.

import Config

config :jar, Jar.Config,
  token: "your api token",
  sandbox: false,
  debug: false,
  mock_http: false

The global client can be fetched like this:

client = Jar.global()

Clients can also be configured at runtime.

client = Jar.configure(%{
  token: "your api token",
  sandbox: false,
  debug: false,
  mock_http: false
%})

API functions take your %Jar.Client{} as the first argument. Here's an example API call to validate an address, using global configuration:

Jar.validate_address(client, %{
  country: "US",
  state: "AZ",
  zip: "85297",
  city: "Gilbert",
  street: "3301 South Greenfield Rd"
})

# {:ok, %{addresses: [...]}}

Testing

By default, tests run against mocks.

Testing against the Sandbox

To instead run tests against the live Sandbox API service, create the following config/test.secret.exs file, substituting your own Sandbox API token:

import Config

config :jar, Jar.Config,
  token: "your token",
  mock_http: false

Endpoints that the Sandbox doesn't support

At least 3 functions can't be tested against the live Sandbox API service.

To prevent you from accidentally altering your live production data or incurring charges on your TaxJar bill, tests for these endpoints are set up to always run against mocks, regardless of test configuration. When altering test code, take care to ensure that this behavior is maintained.

See prod_only_endpoints_test.exs and the always_mocked_production_client_factory/0 function in test/support/factory.ex.

jar's Issues

Add the option to use a global client configuration

Passing a client struct to each call is good because it makes the lib more flexible, but ideally there should also be a way to use a global configuration. Rather than refactor to make the client argument of API functions optional, I think it should suffice for now just to make something like this possible:

Jar.global() # instead of Jar.configure(options)
|> Jar.list_categories()
|> case do
   # ...
end

Mock HTTP request/response for tests

There's a Tesla.Mock adapter that looks promising for this.

Test functions whose API endpoints are missing from the sandbox

They are:

• Jar.list_customers/1
• Jar.validate_address/2
• Jar.validate_vat_number/2

They should probably get checked against the non-sandbox API at least once before everything in tests gets mocked (#1). Careful not to accidentally run the whole test suite against the live, non-sandbox API in the process.

Handle unexpected 204 errors?

When using the address validation endpoint, I momentarily forgot to have my test POST any params. Instead of receiving any kind of error, I got a 204 No Content, which implies success. (This is something I'd consider a bug on TaxJar's end, but it would demand an API version bump if fixed, IMO.)

Anyway, my code's returning {:ok, _} in this case. But it's not okay! What actually happened was the API server more or less rejected the request for lack of appropriate params.

(Cursory testing suggests the problem is probably limited to /addresses/validate.)

Update README to explain the new testing stuff

The README is outdated and still refers to how things were before I updated to get rid of the test secrets thing.

Some level of pre-validation for params?

Related to #8 maybe.

It probably doesn't make sense to go overboard on pre-validating everything possible.

What probably does make sense: If the API endpoint requires params, the Elixir function's signature shouldn't have an optional params arg.`

Tell TaxJar "Validate a VAT number" needs to be flagged in docs as sandbox-unavailable

The endpoint is not available in the Sandbox API, but nowhere does it say that.

Complete API coverage

I made notes of which sections of the API I originally skipped in the jar.ex file, with TODO: comments. Time to actually finish those up.