Class: Assinafy::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/assinafy/configuration.rb,
sig/assinafy.rbs

Overview

SDK configuration values. Client snapshots these values when it builds its connection; construct a new client after changing a configuration.

Examples:

Build from a YAML-style hash (e.g. loaded from config/assinafy.yml)

raw = YAML.load_file('config/assinafy.yml') # => string-keyed Hash
# raw => {
#   "api_key"        => "example_api_key",
#   "account_id"     => "account_example",
#   "base_url"       => "https://api.assinafy.com.br/v1",
#   "webhook_secret" => "gateway_secret",
#   "timeout"        => 30
# }
config = Assinafy::Configuration.from_hash(raw)
config.api_key      # => "example_api_key"
config.   # => "account_example"
config.auth_headers # => { "X-Api-Key" => "example_api_key" }

Constant Summary collapse

DEFAULT_BASE_URL =

Default base URL (production v1 API).

Returns:

  • (String) 
'https://api.assinafy.com.br/v1'
DEFAULT_TIMEOUT =

Default Faraday open/read timeout, in seconds.

Returns:

  • (Integer) 
30

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, token: nil, account_id: nil, base_url: DEFAULT_BASE_URL, webhook_secret: nil, timeout: DEFAULT_TIMEOUT, logger: nil) ⇒ Configuration

Build a configuration directly from keyword arguments. Prefer passing api_key (the documented X-Api-Key mechanism); token is the legacy bearer fallback. base_url has its trailing slash stripped on assignment.

Examples:

Construct with an API key (omits the default base_url)

config = Assinafy::Configuration.new(
  api_key:    'example_api_key',
  account_id: 'account_example'
)
config.base_url     # => "https://api.assinafy.com.br/v1"
config.timeout      # => 30
config.auth_headers # => { "X-Api-Key" => "example_api_key" }

Trailing slash on base_url is stripped

Assinafy::Configuration.new(base_url: 'https://api.assinafy.com.br/v1/').base_url
# => "https://api.assinafy.com.br/v1"

Parameters:

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

    sent as the X-Api-Key header

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

    legacy bearer token (used only when api_key is nil)

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

    default workspace account ID

  • base_url (String) (defaults to: DEFAULT_BASE_URL) —

    API base URL (trailing slash is stripped)

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

    secret for Support::WebhookVerifier

  • timeout (Integer) (defaults to: DEFAULT_TIMEOUT) —

    Faraday open/read timeout in seconds

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

    optional logger for Faraday

Raises:



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/assinafy/configuration.rb', line 68

def initialize(api_key: nil, token: nil, account_id: nil,
               base_url: DEFAULT_BASE_URL, webhook_secret: nil,
               timeout: DEFAULT_TIMEOUT, logger: nil)
  @api_key        = api_key
  @token          = token
  @account_id     = 
  raise ValidationError.new('Base URL is required') unless base_url.is_a?(String)

  @base_url = base_url.strip.sub(%r{/+\z}, '')
  raise ValidationError.new('Base URL is required') if @base_url.empty?

  @webhook_secret = webhook_secret
  @timeout        = normalize_timeout(timeout)
  @logger         = logger
end

Instance Attribute Details

#account_id ⇒ String?

Returns default workspace ID.

Parameters:

  • value (String, nil)

Returns:

  • (String, nil) —

    default workspace ID



42
 
# File 'lib/assinafy/configuration.rb', line 42

attr_accessor :api_key, :token, :account_id, :base_url, :webhook_secret, :timeout, :logger

#api_key ⇒ String?

Returns sent as X-Api-Key.

Parameters:

  • value (String, nil)

Returns:

  • (String, nil) —

    sent as X-Api-Key



42
43
44
 
# File 'lib/assinafy/configuration.rb', line 42

def api_key
  @api_key
end

#base_url ⇒ String

Returns API base URL (trailing slash stripped).

Parameters:

  • value (String)

Returns:

  • (String) —

    API base URL (trailing slash stripped)



42
 
# File 'lib/assinafy/configuration.rb', line 42

attr_accessor :api_key, :token, :account_id, :base_url, :webhook_secret, :timeout, :logger

#logger ⇒ Logger?

Returns:

  • (Logger, nil) 


42
 
# File 'lib/assinafy/configuration.rb', line 42

attr_accessor :api_key, :token, :account_id, :base_url, :webhook_secret, :timeout, :logger

#timeout ⇒ Integer

Returns Faraday timeout in seconds.

Parameters:

  • value (Integer)

Returns:

  • (Integer) —

    Faraday timeout in seconds



42
 
# File 'lib/assinafy/configuration.rb', line 42

attr_accessor :api_key, :token, :account_id, :base_url, :webhook_secret, :timeout, :logger

#token ⇒ String?

Returns legacy bearer token (used when api_key is nil).

Parameters:

  • value (String, nil)

Returns:

  • (String, nil) —

    legacy bearer token (used when api_key is nil)



42
 
# File 'lib/assinafy/configuration.rb', line 42

attr_accessor :api_key, :token, :account_id, :base_url, :webhook_secret, :timeout, :logger

#webhook_secret ⇒ String?

Returns secret for Support::WebhookVerifier.

Parameters:

  • value (String, nil)

Returns:



42
 
# File 'lib/assinafy/configuration.rb', line 42

attr_accessor :api_key, :token, :account_id, :base_url, :webhook_secret, :timeout, :logger

Class Method Details

.from_hash(hash) ⇒ Configuration

Build a Assinafy::Configuration from a Hash with string or symbol keys. Accepts both 'token' and 'access_token' for backwards compatibility. Missing keys fall back to defaults (base_url => DEFAULT_BASE_URL, timeout => DEFAULT_TIMEOUT); numeric strings are accepted, while invalid and non-positive values raise ValidationError.

Examples:

Symbol-keyed hash with the legacy access_token alias

config = Assinafy::Configuration.from_hash(
  access_token: 'legacy-bearer-abc123',
  account_id:   'account_example',
  timeout:      '45'
)
config.token        # => "legacy-bearer-abc123"
config.api_key      # => nil
config.timeout      # => 45
config.base_url     # => "https://api.assinafy.com.br/v1"
config.auth_headers # => { "Authorization" => "Bearer legacy-bearer-abc123" }

Parameters:

  • hash (Hash{String,Symbol=>Object})

Returns:

Raises:



104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/assinafy/configuration.rb', line 104

def self.from_hash(hash)
  raise ValidationError.new('Configuration must be a Hash') unless hash.is_a?(Hash)

  h = hash.transform_keys(&:to_s)
  new(
    api_key:        h['api_key'],
    token:          h['token'] || h['access_token'],
    account_id:     h['account_id'],
    base_url:       h.key?('base_url') ? h['base_url'] : DEFAULT_BASE_URL,
    webhook_secret: h['webhook_secret'],
    timeout:        h.key?('timeout') ? h['timeout'] : DEFAULT_TIMEOUT,
    logger:         h['logger']
  )
end

Instance Method Details

#auth_headers ⇒ Hash{String=>String}

Return the HTTP headers used to authenticate requests, preferring X-Api-Key (the documented mechanism) over a bearer token. When api_key is set it wins; otherwise a non-nil token produces an Authorization: Bearer header; with neither credential set an empty Hash is returned.

Examples:

api_key takes precedence over token

Assinafy::Configuration.new(api_key: 'k', token: 't').auth_headers
# => { "X-Api-Key" => "k" }

Bearer fallback when only a token is present

Assinafy::Configuration.new(token: 't').auth_headers
# => { "Authorization" => "Bearer t" }

No credentials configured

Assinafy::Configuration.new.auth_headers
# => {}

Returns:

  • (Hash{String=>String}) —

    one of { "X-Api-Key" => ... }, { "Authorization" => "Bearer ..." }, or {}



138
139
140
141
142
143
144
145
 
# File 'lib/assinafy/configuration.rb', line 138

def auth_headers
  key = api_key.to_s.strip
  bearer = token.to_s.strip
  return { 'X-Api-Key' => key } unless key.empty?
  return { 'Authorization' => "Bearer #{bearer}" } unless bearer.empty?

  {}
end