Class: Boldsign::Client

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

Overview

HTTP client for the BoldSign REST API.

Holds API credentials and exposes one accessor per resource group (‘documents`, `templates`, `contacts`, …). Each accessor returns a memoized resource object whose methods wrap individual endpoints.

Low-level verb methods (#get, #post, #put, #patch, #delete, #download) are also available for hitting any endpoint directly.

Authenticates with either an API key (‘X-API-KEY`) or OAuth 2.0 (`Authorization: Bearer`). For OAuth, pass `client_id`/`client_secret` and the client fetches + caches a token via the client credentials grant; or pass a `access_token` you obtained yourself.

Examples:

API key

client = Boldsign::Client.new(api_key: ENV["BOLDSIGN_API_KEY"], region: :us)
client.documents.send_document(title: "NDA", signers: [...])

OAuth client credentials

client = Boldsign::Client.new(
  client_id: ENV["BOLDSIGN_CLIENT_ID"],
  client_secret: ENV["BOLDSIGN_CLIENT_SECRET"],
  region: :us
)

Constant Summary collapse

DEFAULT_BASE_URL =

Default region (US).

"https://api.boldsign.com".freeze
USER_AGENT =

User-Agent header value sent on every request.

"boldsign-ruby/#{Boldsign::VERSION}".freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, client_id: nil, client_secret: nil, access_token: nil, scope: nil, token_url: nil, region: nil, base_url: nil, adapter: Faraday.default_adapter, logger: nil) ⇒ Client

Returns a new instance of Client.

Parameters:

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

    BoldSign API key. Falls back to ‘ENV`.

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

    OAuth app client ID (enables the client credentials grant).

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

    OAuth app client secret (required with ‘client_id`).

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

    A pre-obtained OAuth bearer token (used as-is, not refreshed).

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

    OAuth scope to request (defaults to AccessToken::DEFAULT_SCOPE).

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

    Override for the full OAuth token endpoint URL.

  • region (Symbol, nil) (defaults to: nil) —

    One of ‘:us`, `:eu`, `:ca`, `:au`. Ignored if `base_url`/`token_url` is given.

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

    Explicit API base URL override.

  • adapter (Symbol) (defaults to: Faraday.default_adapter) —

    Faraday adapter (defaults to ‘Faraday.default_adapter`).

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger; when present, Faraday’s logger middleware is enabled.

Raises:



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/boldsign/client.rb', line 53

def initialize(api_key: nil, client_id: nil, client_secret: nil, access_token: nil,
               scope: nil, token_url: nil, region: nil, base_url: nil,
               adapter: Faraday.default_adapter, logger: nil)
  @api_key = api_key || ENV["BOLDSIGN_API_KEY"]
  @static_access_token = access_token
  @base_url = base_url || Boldsign::REGIONS[region&.to_sym] || DEFAULT_BASE_URL
  @adapter = adapter
  @logger = logger

  if present?(client_id) && present?(client_secret)
    @auth_mode = :oauth
    @access_token = AccessToken.new(
      client_id: client_id, client_secret: client_secret,
      token_url: token_url || default_token_url(region),
      scope: scope || AccessToken::DEFAULT_SCOPE, adapter: adapter
    )
  elsif present?(@static_access_token)
    @auth_mode = :bearer
  elsif present?(@api_key)
    @auth_mode = :api_key
  else
    raise ConfigurationError,
          "Missing BoldSign credentials: provide client_id/client_secret, access_token, or api_key"
  end
end

Instance Attribute Details

#api_key ⇒ String? (readonly)

Returns the API key in use, when authenticating via API key.

Returns:

  • (String, nil) —

    the API key in use, when authenticating via API key.



34
35
36
 
# File 'lib/boldsign/client.rb', line 34

def api_key
  @api_key
end

#auth_mode ⇒ Symbol (readonly)

Returns the resolved auth mode (‘:api_key`, `:oauth`, or `:bearer`).

Returns:

  • (Symbol) —

    the resolved auth mode (‘:api_key`, `:oauth`, or `:bearer`).



37
38
39
 
# File 'lib/boldsign/client.rb', line 37

def auth_mode
  @auth_mode
end

#base_url ⇒ String (readonly)

Returns the resolved base URL (region or explicit override).

Returns:

  • (String) —

    the resolved base URL (region or explicit override).



40
41
42
 
# File 'lib/boldsign/client.rb', line 40

def base_url
  @base_url
end

Instance Method Details

#brand ⇒ Resources::Brand

Returns:



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

def brand;                 @brand ||= Resources::Brand.new(self); end

#contact_groups ⇒ Resources::ContactGroup

Returns:



84
 
# File 'lib/boldsign/client.rb', line 84

def contact_groups;        @contact_groups ||= Resources::ContactGroup.new(self); end

#contacts ⇒ Resources::Contact

Returns:



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

def contacts;              @contacts ||= Resources::Contact.new(self); end

#custom_fields ⇒ Resources::CustomField

Returns:



86
 
# File 'lib/boldsign/client.rb', line 86

def custom_fields;         @custom_fields ||= Resources::CustomField.new(self); end

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

Issue a DELETE request.

Parameters:

  • path (String) —

    request path.

  • params (Hash) (defaults to: {}) —

    query string parameters.



137
138
139
 
# File 'lib/boldsign/client.rb', line 137

def delete(path, params = {})
  request(:delete, path, params: params)
end

#documents ⇒ Resources::Document

Returns:



88
 
# File 'lib/boldsign/client.rb', line 88

def documents;             @documents ||= Resources::Document.new(self); end

#download(path, params = {}) ⇒ String

Issue a GET request and return the raw response body without JSON parsing. Use for binary endpoints (downloads, audit logs, attachments).

Parameters:

  • path (String) —

    request path.

  • params (Hash) (defaults to: {}) —

    query string parameters.

Returns:

  • (String) —

    raw response bytes.

Raises:

  • (Error) —

    on any non-success HTTP status.



147
148
149
150
151
152
153
 
# File 'lib/boldsign/client.rb', line 147

def download(path, params = {})
  response = connection.get(path) do |req|
    req.params.update(params) if params && !params.empty?
  end
  handle_errors(response)
  response.body
end

#get(path, params = {}) ⇒ Hash, ...

Issue a GET request.

Parameters:

  • path (String) —

    request path (e.g. ‘/v1/document/list`).

  • params (Hash) (defaults to: {}) —

    query string parameters.

Returns:

  • (Hash, Array, String, nil) —

    parsed JSON body, or raw body for non-JSON responses.

Raises:

  • (Error) —

    on any non-success HTTP status.



107
108
109
 
# File 'lib/boldsign/client.rb', line 107

def get(path, params = {})
  request(:get, path, params: params)
end

#identity_verification ⇒ Resources::IdentityVerification

Returns:



90
 
# File 'lib/boldsign/client.rb', line 90

def identity_verification; @identity_verification ||= Resources::IdentityVerification.new(self); end

#patch(path, body: nil, params: {}) ⇒ Object

Issue a PATCH request. See #post for parameter semantics.



130
131
132
 
# File 'lib/boldsign/client.rb', line 130

def patch(path, body: nil, params: {})
  request(:patch, path, body: body, params: params)
end

#plan ⇒ Resources::Plan

Returns:



92
 
# File 'lib/boldsign/client.rb', line 92

def plan;                  @plan ||= Resources::Plan.new(self); end

#post(path, body: nil, params: {}, multipart: false) ⇒ Hash, ...

Issue a POST request.

Parameters:

  • path (String) —

    request path.

  • body (Hash, String, nil) (defaults to: nil) —

    request body. Hashes are JSON-encoded; pre-serialized JSON strings are sent as-is.

  • params (Hash) (defaults to: {}) —

    query string parameters.

  • multipart (Boolean) (defaults to: false) —

    when ‘true`, body is sent as `multipart/form-data` (include `Faraday::Multipart::FilePart` values to upload files).

Returns:

  • (Hash, Array, String, nil)

Raises:

  • (Error) —

    on any non-success HTTP status.



120
121
122
 
# File 'lib/boldsign/client.rb', line 120

def post(path, body: nil, params: {}, multipart: false)
  request(:post, path, body: body, params: params, multipart: multipart)
end

#put(path, body: nil, params: {}) ⇒ Object

Issue a PUT request. See #post for parameter semantics.



125
126
127
 
# File 'lib/boldsign/client.rb', line 125

def put(path, body: nil, params: {})
  request(:put, path, body: body, params: params)
end

#sender_identities ⇒ Resources::SenderIdentity

Returns:



94
 
# File 'lib/boldsign/client.rb', line 94

def sender_identities;     @sender_identities ||= Resources::SenderIdentity.new(self); end

#teams ⇒ Resources::Team

Returns:



96
 
# File 'lib/boldsign/client.rb', line 96

def teams;                 @teams ||= Resources::Team.new(self); end

#templates ⇒ Resources::Template

Returns:



98
 
# File 'lib/boldsign/client.rb', line 98

def templates;             @templates ||= Resources::Template.new(self); end

#users ⇒ Resources::User

Returns:



100
 
# File 'lib/boldsign/client.rb', line 100

def users;                 @users ||= Resources::User.new(self); end