Class: Api::Taxjar::Client

Inherits:
Object
  • Object
show all
Defined in:
app/services/api/taxjar/client.rb

Overview

Direct Faraday client for the TaxJar API v2.

Replaces the abandoned taxjar-ruby gem (3.0.4), which was incompatible
with the http gem 6.x (AppSignal #5647) and required a monkeypatch.
Follows the precedent set by Minfraud::InsightsClient (#940).

Only the endpoints and response fields Heatwave actually uses are
implemented — see the surface map in
doc/tasks/202606011409_EXTRACT_TAXJAR_DIRECT_CLIENT.md. Non-2xx responses
raise Error subclasses (by status); transport errors are
wrapped as Error::ServerError so existing retry / rescue
paths still fire.

See Also:

Constant Summary collapse

DEFAULT_API_URL = 
'https://api.taxjar.com'
API_VERSION = 
'2022-01-24'
TIMEOUT_SECONDS = 
30
OPEN_TIMEOUT_SECONDS = 
10

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, api_url: nil) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String) —

    TaxJar API token (Bearer auth)

  • api_url (String, nil) (defaults to: nil) —

    base URL; defaults to DEFAULT_API_URL



27
28
29
30
 
# File 'app/services/api/taxjar/client.rb', line 27

def initialize(api_key:, api_url: nil)
  @api_key = api_key
  @api_url = api_url.presence || DEFAULT_API_URL
end

Instance Method Details

#categories ⇒ Array<Category>

GET /v2/categories

Returns:



59
60
61
62
63
 
# File 'app/services/api/taxjar/client.rb', line 59

def categories
  get('/v2/categories').fetch('categories', []).map do |c|
    Category.new(name: c['name'], product_tax_code: c['product_tax_code'], description: c['description'])
  end
end

#create_customer(params) ⇒ Customer

Returns:



79
80
81
 
# File 'app/services/api/taxjar/client.rb', line 79

def create_customer(params)
  customer(post('/v2/customers', params))
end

#create_order(params) ⇒ Transaction

Returns:



108
109
110
 
# File 'app/services/api/taxjar/client.rb', line 108

def create_order(params)
  transaction(post('/v2/transactions/orders', params), 'order')
end

#create_refund(params) ⇒ Transaction

Returns:



137
138
139
 
# File 'app/services/api/taxjar/client.rb', line 137

def create_refund(params)
  transaction(post('/v2/transactions/refunds', params), 'refund')
end

#delete_customer(id, params = {}) ⇒ Customer

Returns:



90
91
92
 
# File 'app/services/api/taxjar/client.rb', line 90

def delete_customer(id, params = {})
  customer(delete("/v2/customers/#{id}", params))
end

#delete_order(id, params = {}) ⇒ Transaction

Returns:



119
120
121
 
# File 'app/services/api/taxjar/client.rb', line 119

def delete_order(id, params = {})
  transaction(delete("/v2/transactions/orders/#{id}", params), 'order')
end

#delete_refund(id, params = {}) ⇒ Transaction

Returns:



148
149
150
 
# File 'app/services/api/taxjar/client.rb', line 148

def delete_refund(id, params = {})
  transaction(delete("/v2/transactions/refunds/#{id}", params), 'refund')
end

#list_customers(params = {}) ⇒ Array<String>

Returns TaxJar customer ids.

Returns:

  • (Array<String>) —

    TaxJar customer ids



68
69
70
 
# File 'app/services/api/taxjar/client.rb', line 68

def list_customers(params = {})
  get('/v2/customers', params).fetch('customers', [])
end

#list_orders(params = {}) ⇒ Array<String>

Returns order transaction ids.

Returns:

  • (Array<String>) —

    order transaction ids



97
98
99
 
# File 'app/services/api/taxjar/client.rb', line 97

def list_orders(params = {})
  get('/v2/transactions/orders', params).fetch('orders', [])
end

#list_refunds(params = {}) ⇒ Array<String>

Returns refund transaction ids.

Returns:

  • (Array<String>) —

    refund transaction ids



126
127
128
 
# File 'app/services/api/taxjar/client.rb', line 126

def list_refunds(params = {})
  get('/v2/transactions/refunds', params).fetch('refunds', [])
end

#show_customer(id, params = {}) ⇒ Customer

Returns:

Raises:



74
75
76
 
# File 'app/services/api/taxjar/client.rb', line 74

def show_customer(id, params = {})
  customer(get("/v2/customers/#{id}", params))
end

#show_order(id, params = {}) ⇒ Transaction

Returns:

Raises:



103
104
105
 
# File 'app/services/api/taxjar/client.rb', line 103

def show_order(id, params = {})
  transaction(get("/v2/transactions/orders/#{id}", params), 'order')
end

#show_refund(id, params = {}) ⇒ Transaction

Returns:

Raises:



132
133
134
 
# File 'app/services/api/taxjar/client.rb', line 132

def show_refund(id, params = {})
  transaction(get("/v2/transactions/refunds/#{id}", params), 'refund')
end

#summary_rates ⇒ Array<SummaryRate>

GET /v2/summary_rates

Returns:



50
51
52
53
54
55
 
# File 'app/services/api/taxjar/client.rb', line 50

def summary_rates
  get('/v2/summary_rates').fetch('summary_rates', []).map do |r|
    SummaryRate.new(country_code: r['country_code'], country: r['country'],
                    region_code: r['region_code'], region: r['region'])
  end
end

#tax_for_order(params) ⇒ TaxResult

POST /v2/taxes — calculate sales tax for an order.

Parameters:

  • params (Hash) —

    from/to address, line_items, shipping, …

Returns:



35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'app/services/api/taxjar/client.rb', line 35

def tax_for_order(params)
  body = post('/v2/taxes', params).fetch('tax', {})
  line_items = Array(body['breakdown'] && body['breakdown']['line_items']).map do |li|
    TaxLineItem.new(
      id: li['id'],
      taxable_amount: li['taxable_amount'],
      tax_collectable: li['tax_collectable'],
      combined_tax_rate: li['combined_tax_rate']
    )
  end
  TaxResult.new(rate: body['rate'], freight_taxable: body['freight_taxable'] || false, line_items:)
end

#update_customer(params) ⇒ Customer

Returns:



84
85
86
87
 
# File 'app/services/api/taxjar/client.rb', line 84

def update_customer(params)
  id = params.fetch(:customer_id)
  customer(put("/v2/customers/#{id}", params))
end

#update_order(params) ⇒ Transaction

Returns:



113
114
115
116
 
# File 'app/services/api/taxjar/client.rb', line 113

def update_order(params)
  id = params.fetch(:transaction_id)
  transaction(put("/v2/transactions/orders/#{id}", params), 'order')
end

#update_refund(params) ⇒ Transaction

Returns:



142
143
144
145
 
# File 'app/services/api/taxjar/client.rb', line 142

def update_refund(params)
  id = params.fetch(:transaction_id)
  transaction(put("/v2/transactions/refunds/#{id}", params), 'refund')
end