Class: Nombaone::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/nombaone/client.rb,
sig/nombaone/client.rbs

Overview

The NombaOne API client. Construct one with your secret key; it derives the host from the key's prefix and exposes every resource as a namespace.

Examples:

nombaone = Nombaone.new(ENV["NOMBAONE_API_KEY"])

plan = nombaone.plans.create(name: "Pro")
price = nombaone.plans.prices.create(plan.id, unit_amount_in_kobo: 250_000, interval: "month")
customer = nombaone.customers.create(email: "ada@example.com", name: "Ada Lovelace")
method = nombaone.sandbox.create_payment_method(customer_id: customer.id)
subscription = nombaone.subscriptions.create(
  customer_id: customer.id, price_id: price.id, payment_method_id: method.id
)
subscription.status # => "active"

Constant Summary collapse

BASE_URLS =

Default host per environment. Overridable with the base_url: option.

Returns:

  • (Hash[String, String]) 
{
  "sandbox" => "https://sandbox.api.nombaone.xyz",
  "live" => "https://api.nombaone.xyz",
}.freeze
DEFAULT_TIMEOUT =

Per-attempt request timeout, in seconds.

Returns:

  • (Integer) 
30
DEFAULT_MAX_RETRIES =

Automatic retries (3 attempts total). Retried POSTs reuse one idempotency key.

Returns:

  • (Integer) 
2

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key = nil, base_url: nil, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES, http: nil, default_headers: nil, sleeper: nil) ⇒ Client

Returns a new instance of Client.

Parameters:

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

    your secret key (nbo_sandbox_… / nbo_live_…). Defaults to ENV["NOMBAONE_API_KEY"]. Server-side only — never ship it to a browser or mobile app.

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

    override the API origin (no /v1). Defaults to the host matching the key's environment; required if the key prefix is unrecognized.

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

    per-attempt timeout in seconds (default 30).

  • max_retries (Integer) (defaults to: DEFAULT_MAX_RETRIES) —

    automatic retry budget (default 2).

  • http (#execute, nil) (defaults to: nil) —

    an injectable connection for tests/proxies; defaults to a Net::HTTP transport.

  • default_headers (Hash{String => String}, nil) (defaults to: nil) —

    extra headers on every request.

Raises:

  • (Nombaone::Error) —

    if the key is missing or its prefix is unrecognized and no base_url was given.



50
51
52
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
78
 
# File 'lib/nombaone/client.rb', line 50

def initialize(api_key = nil, base_url: nil, timeout: DEFAULT_TIMEOUT,
               max_retries: DEFAULT_MAX_RETRIES, http: nil, default_headers: nil, sleeper: nil)
  resolved_key = api_key || ENV.fetch("NOMBAONE_API_KEY", nil)
  if resolved_key.nil? || resolved_key.empty?
    raise Error,
          "Missing API key — set the NOMBAONE_API_KEY environment variable, or pass one: " \
          'Nombaone.new("nbo_sandbox_…"). Create keys in the dashboard under API keys.'
  end

  derived = derive_mode(resolved_key)
  if derived.nil? && base_url.nil?
    raise Error,
          'Unrecognized API key format — expected a key starting with "nbo_sandbox_" or ' \
          '"nbo_live_". Copy the key exactly as shown in the dashboard, or pass an explicit ' \
          "base_url: if you are targeting a custom host."
  end

  @mode = derived || "sandbox"
  @base_url = (base_url || BASE_URLS.fetch(@mode)).sub(%r{/+\z}, "")
  @http = Internal::HTTPClient.new(
    api_key: resolved_key,
    base_url: @base_url,
    timeout: timeout,
    max_retries: max_retries,
    connection: http || Internal::NetHTTPConnection.new,
    default_headers: default_headers,
    sleeper: sleeper,
  )
end

Instance Attribute Details

#base_url ⇒ String (readonly)

Returns the API origin in use (no /v1).

Returns:

  • (String) —

    the API origin in use (no /v1).



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

def base_url
  @base_url
end

#mode ⇒ String (readonly)

Returns the environment this client talks to ("sandbox"/"live"), derived from the key prefix.

Returns:

  • (String) —

    the environment this client talks to ("sandbox"/"live"), derived from the key prefix.



32
33
34
 
# File 'lib/nombaone/client.rb', line 32

def mode
  @mode
end

Instance Method Details

#coupons ⇒ Resources::Coupons

Returns reusable discount rules.

Returns:



91
92
 
# File 'lib/nombaone/client.rb', line 91

def coupons = @coupons ||= Resources::Coupons.new(self)
# @return [Resources::PaymentMethods] cards, mandates, virtual accounts.

#customers ⇒ Resources::Customers

Returns the people and businesses you bill.

Returns:



81
82
 
# File 'lib/nombaone/client.rb', line 81

def customers = @customers ||= Resources::Customers.new(self)
# @return [Resources::Plans] your catalog (prices nest under `plans.prices`).

#events ⇒ Resources::Events

Returns the domain-event log — your reconciliation backstop.

Returns:



101
102
 
# File 'lib/nombaone/client.rb', line 101

def events = @events ||= Resources::Events.new(self)
# @return [Resources::Organization] org settings + billing/dunning policy.

#invoices ⇒ Resources::Invoices

Returns what billing cycles produced (read + void).

Returns:



89
90
 
# File 'lib/nombaone/client.rb', line 89

def invoices = @invoices ||= Resources::Invoices.new(self)
# @return [Resources::Coupons] reusable discount rules.

#mandates ⇒ Resources::Mandates

Returns direct-debit mandates (async NIBSS consent).

Returns:



95
96
 
# File 'lib/nombaone/client.rb', line 95

def mandates = @mandates ||= Resources::Mandates.new(self)
# @return [Resources::Settlements] settlements, refunds, payouts, escrow.

#metrics ⇒ Resources::Metrics

Returns billing KPIs computed from the ledger.

Returns:



105
106
 
# File 'lib/nombaone/client.rb', line 105

def metrics = @metrics ||= Resources::Metrics.new(self)
# @return [Resources::Sandbox] sandbox-only simulation instruments.

#organization ⇒ Resources::Organization

Returns org settings + billing/dunning policy.

Returns:



103
104
 
# File 'lib/nombaone/client.rb', line 103

def organization = @organization ||= Resources::Organization.new(self)
# @return [Resources::Metrics] billing KPIs computed from the ledger.

#payment_methods ⇒ Resources::PaymentMethods

Returns cards, mandates, virtual accounts.

Returns:



93
94
 
# File 'lib/nombaone/client.rb', line 93

def payment_methods = @payment_methods ||= Resources::PaymentMethods.new(self)
# @return [Resources::Mandates] direct-debit mandates (async NIBSS consent).

#plans ⇒ Resources::Plans

Returns your catalog (prices nest under plans.prices).

Returns:



83
84
 
# File 'lib/nombaone/client.rb', line 83

def plans = @plans ||= Resources::Plans.new(self)
# @return [Resources::Prices] immutable amounts and cadences.

#prices ⇒ Resources::Prices

Returns immutable amounts and cadences.

Returns:



85
86
 
# File 'lib/nombaone/client.rb', line 85

def prices = @prices ||= Resources::Prices.new(self)
# @return [Resources::Subscriptions] the core billing object.

#request(method:, path:, query: nil, body: nil, options: nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Execute a single-object request and return the wrapped NombaObject.



117
118
119
120
 
# File 'lib/nombaone/client.rb', line 117

def request(method:, path:, query: nil, body: nil, options: nil)
  result = perform(method: method, path: path, query: query, body: body, options: options)
  wrap_data(result)
end

#request_page(method:, path:, query: nil, options: nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Execute a list request and return a Page that auto-paginates.



124
125
126
127
128
129
130
 
# File 'lib/nombaone/client.rb', line 124

def request_page(method:, path:, query: nil, options: nil)
  raw_query = query || {}
  fetcher = lambda do |query_for_page|
    perform(method: method, path: path, query: query_for_page, options: options)
  end
  Page.new(fetcher: fetcher, query: raw_query, result: fetcher.call(raw_query))
end

#sandbox ⇒ Resources::Sandbox

Returns sandbox-only simulation instruments.

Returns:



107
 
# File 'lib/nombaone/client.rb', line 107

def sandbox = @sandbox ||= Resources::Sandbox.new(self)

#settlements ⇒ Resources::Settlements

Returns settlements, refunds, payouts, escrow.

Returns:



97
98
 
# File 'lib/nombaone/client.rb', line 97

def settlements = @settlements ||= Resources::Settlements.new(self)
# @return [Resources::WebhookEndpoints] webhook endpoint management (REST).

#subscriptions ⇒ Resources::Subscriptions

Returns the core billing object.

Returns:



87
88
 
# File 'lib/nombaone/client.rb', line 87

def subscriptions = @subscriptions ||= Resources::Subscriptions.new(self)
# @return [Resources::Invoices] what billing cycles produced (read + void).

#webhook_endpoints ⇒ Resources::WebhookEndpoints

Returns webhook endpoint management (REST).

Returns:



99
100
 
# File 'lib/nombaone/client.rb', line 99

def webhook_endpoints = @webhook_endpoints ||= Resources::WebhookEndpoints.new(self)
# @return [Resources::Events] the domain-event log — your reconciliation backstop.

#webhooks ⇒ Nombaone::Webhooks

A Webhooks helper bound to this client. Verification needs only the signing secret, so Nombaone.webhooks works without a client too.

Returns:



113
 
# File 'lib/nombaone/client.rb', line 113

def webhooks = @webhooks ||= Webhooks.new