Class: SuperPDP::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/super_pdp/client.rb

Overview

Thin HTTP client for the SUPER PDP API.

Auth: pass an access_token directly (e.g. one you obtained via the authorization_code flow to act on a user's behalf), or pass +client_id+/+client_secret+ to have the client fetch and refresh a client_credentials token automatically (acts on your own data, api-key-like).

Constant Summary collapse

DEFAULT_BASE_URL = 
"https://api.superpdp.tech"
API_PREFIX = 
"/v1.beta"
USER_AGENT = 
"super_pdp/#{VERSION} (Ruby #{RUBY_VERSION})".freeze
RETRYABLE_STATUSES =

Transient failures retried automatically (idempotent verbs only).

[429, 502, 503, 504].freeze
RETRYABLE_METHODS = 
%i[get delete].freeze
RETRYABLE_ERRORS = 
[Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET,
Errno::ECONNREFUSED, IOError].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(access_token: nil, client_id: nil, client_secret: nil, base_url: DEFAULT_BASE_URL, open_timeout: 10, read_timeout: 60, max_retries: 2, retry_base: 0.5) ⇒ Client

Returns a new instance of Client.

Raises:

  • (ArgumentError) 


27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/super_pdp/client.rb', line 27

def initialize(access_token: nil, client_id: nil, client_secret: nil,
               base_url: DEFAULT_BASE_URL, open_timeout: 10, read_timeout: 60,
               max_retries: 2, retry_base: 0.5)
  @access_token = access_token
  @client_id = client_id
  @client_secret = client_secret
  @base_url = base_url
  @open_timeout = open_timeout
  @read_timeout = read_timeout
  @max_retries = max_retries
  @retry_base = retry_base
  @token_expires_at = nil
  @token_mutex = Mutex.new

  return if access_token || (client_id && client_secret)

  raise ArgumentError, "provide access_token, or client_id and client_secret"
end

Instance Attribute Details

#base_url ⇒ Object (readonly)

Returns the value of attribute base_url.



25
26
27
 
# File 'lib/super_pdp/client.rb', line 25

def base_url
  @base_url
end

Instance Method Details

#b2c_payments(**params) ⇒ Object 



71
 
# File 'lib/super_pdp/client.rb', line 71

def b2c_payments(**params) = get("/b2c_payments", params)

#b2c_transactions(**params) ⇒ Object 



69
 
# File 'lib/super_pdp/client.rb', line 69

def b2c_transactions(**params) = get("/b2c_transactions", params)

#companies_me(**params) ⇒ Object

--- Resource helpers (thin wrappers over the raw verbs) --------------



48
 
# File 'lib/super_pdp/client.rb', line 48

def companies_me(**params) = get("/companies/me", params)

#convert_invoice(body, **params) ⇒ Object 



55
 
# File 'lib/super_pdp/client.rb', line 55

def convert_invoice(body, **params) = post("/invoices/convert", body, params)

#create_b2c_payment(body) ⇒ Object 



72
 
# File 'lib/super_pdp/client.rb', line 72

def create_b2c_payment(body) = post("/b2c_payments", body)

#create_b2c_transactions(body) ⇒ Object 



70
 
# File 'lib/super_pdp/client.rb', line 70

def create_b2c_transactions(body) = post("/b2c_transactions", body)

#create_directory_entry(body) ⇒ Object 



76
 
# File 'lib/super_pdp/client.rb', line 76

def create_directory_entry(body) = post("/directory_entries", body)

#create_invoice(body, **params) ⇒ Object 



54
 
# File 'lib/super_pdp/client.rb', line 54

def create_invoice(body, **params) = post("/invoices", body, params)

#create_invoice_event(body) ⇒ Object 



63
 
# File 'lib/super_pdp/client.rb', line 63

def create_invoice_event(body) = post("/invoice_events", body)

#delete(path, query = {}) ⇒ Object 



106
 
# File 'lib/super_pdp/client.rb', line 106

def delete(path, query = {}) = request(:delete, path, query: query)

#delete_directory_entry(id) ⇒ Object 



77
 
# File 'lib/super_pdp/client.rb', line 77

def delete_directory_entry(id) = delete("/directory_entries/#{id}")

#directory_entries(**params) ⇒ Object 



74
 
# File 'lib/super_pdp/client.rb', line 74

def directory_entries(**params) = get("/directory_entries", params)

#directory_entry(id, **params) ⇒ Object 



75
 
# File 'lib/super_pdp/client.rb', line 75

def directory_entry(id, **params) = get("/directory_entries/#{id}", params)

#download_invoice(id, **params) ⇒ Object

Raw invoice file bytes (not JSON) — returns the String body.



60
 
# File 'lib/super_pdp/client.rb', line 60

def download_invoice(id, **params) = request(:get, "/invoices/#{id}/download", query: params, raw: true)

#each_item(path, **params, &block) ⇒ Object

Iterate a list endpoint across all pages, yielding each item. Uses the API's cursor pagination (starting_after_id + has_after). Returns an Enumerator when no block is given.



87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/super_pdp/client.rb', line 87

def each_item(path, **params, &block)
  return enum_for(:each_item, path, **params) unless block_given?

  cursor = params[:starting_after_id]
  loop do
    page = get(path, params.merge(starting_after_id: cursor).compact)
    data = page["data"] || []
    data.each(&block)
    break unless page["has_after"] && !data.empty?

    cursor = data.last["id"]
  end
end

#enroll_company(body) ⇒ Object 



49
 
# File 'lib/super_pdp/client.rb', line 49

def enroll_company(body) = post("/companies", body)

#ereporting(id, **params) ⇒ Object 



66
 
# File 'lib/super_pdp/client.rb', line 66

def ereporting(id, **params) = get("/ereportings/#{id}", params)

#ereportings(**params) ⇒ Object 



65
 
# File 'lib/super_pdp/client.rb', line 65

def ereportings(**params) = get("/ereportings", params)

#french_directory_companies(**params) ⇒ Object 



79
 
# File 'lib/super_pdp/client.rb', line 79

def french_directory_companies(**params) = get("/french_directory/companies", params)

#french_directory_entries(**params) ⇒ Object 



80
 
# File 'lib/super_pdp/client.rb', line 80

def french_directory_entries(**params) = get("/french_directory/entries", params)

#generate_test_invoice(**params) ⇒ Object 



57
 
# File 'lib/super_pdp/client.rb', line 57

def generate_test_invoice(**params) = get("/invoices/generate_test_invoice", params)

#get(path, query = {}) ⇒ Object

--- Raw verbs --------------------------------------------------------



103
 
# File 'lib/super_pdp/client.rb', line 103

def get(path, query = {}) = request(:get, path, query: query)

#invoice(id, **params) ⇒ Object 



53
 
# File 'lib/super_pdp/client.rb', line 53

def invoice(id, **params) = get("/invoices/#{id}", params)

#invoice_events(**params) ⇒ Object 



62
 
# File 'lib/super_pdp/client.rb', line 62

def invoice_events(**params) = get("/invoice_events", params)

#invoices(**params) ⇒ Object 



52
 
# File 'lib/super_pdp/client.rb', line 52

def invoices(**params) = get("/invoices", params)

#oauth2_session_me(**params) ⇒ Object 



82
 
# File 'lib/super_pdp/client.rb', line 82

def oauth2_session_me(**params) = get("/oauth2_sessions/me", params)

#patch(path, body = {}, query = {}) ⇒ Object 



105
 
# File 'lib/super_pdp/client.rb', line 105

def patch(path, body = {}, query = {}) = request(:patch, path, body: body, query: query)

#post(path, body = {}, query = {}) ⇒ Object 



104
 
# File 'lib/super_pdp/client.rb', line 104

def post(path, body = {}, query = {}) = request(:post, path, body: body, query: query)

#preview_ereporting(**params) ⇒ Object 



67
 
# File 'lib/super_pdp/client.rb', line 67

def preview_ereporting(**params) = get("/ereportings/preview", params)

#request(method, path, query: {}, body: nil, raw: false) ⇒ Object

Retries transient failures (429 + 502/503/504 + connection errors) with backoff for idempotent verbs only. See RETRYABLE_* constants.



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/super_pdp/client.rb', line 110

def request(method, path, query: {}, body: nil, raw: false)
  uri = build_uri(path, query)
  attempt = 0
  loop do
    attempt += 1
    res =
      begin
        perform(method, uri, body)
      rescue *RETRYABLE_ERRORS
        raise unless retryable?(method, attempt)

        sleep backoff(attempt)
        next
      end
    return handle_response(res, raw: raw) unless retry_status?(method, res.code.to_i, attempt)

    sleep(retry_after(res) || backoff(attempt))
  end
end

#update_company_vat_regime(body) ⇒ Object 



50
 
# File 'lib/super_pdp/client.rb', line 50

def update_company_vat_regime(body) = patch("/companies", body)

#validation_report(body) ⇒ Object 



56
 
# File 'lib/super_pdp/client.rb', line 56

def validation_report(body) = post("/validation_reports", body)