Class: Orb::Client

Inherits:
Internal::Transport::BaseClient show all
Defined in:
lib/orb/client.rb,
sig/orb/client.rbs

Constant Summary collapse

DEFAULT_MAX_RETRIES =

Default max number of retries to attempt after a failed retryable request.

Returns:

  • (2) 
2
DEFAULT_TIMEOUT_IN_SECONDS =

Default per-request timeout.

Returns:

  • (Float) 
60.0
DEFAULT_INITIAL_RETRY_DELAY =

Default initial retry delay in seconds. Overall delay is calculated using exponential backoff + jitter.

Returns:

  • (Float) 
0.5
DEFAULT_MAX_RETRY_DELAY =

Default max retry delay in seconds.

Returns:

  • (Float) 
8.0

Constants inherited from Internal::Transport::BaseClient

Internal::Transport::BaseClient::MAX_REDIRECTS, Internal::Transport::BaseClient::Orb, Internal::Transport::BaseClient::PLATFORM_HEADERS

Instance Attribute Summary collapse

Attributes inherited from Internal::Transport::BaseClient

#base_url, #headers, #idempotency_header, #initial_retry_delay, #max_retries, #max_retry_delay, #requester, #timeout

Instance Method Summary collapse

Methods inherited from Internal::Transport::BaseClient

follow_redirect, #inspect, reap_connection!, #request, #send_request, should_retry?, validate!

Methods included from Internal::Util::SorbetRuntimeSupport

#const_missing, #define_sorbet_constant!, #sorbet_constant_defined?, #to_sorbet_type, to_sorbet_type

Constructor Details

#initialize(api_key: ENV["ORB_API_KEY"], webhook_secret: ENV["ORB_WEBHOOK_SECRET"], base_url: ENV["ORB_BASE_URL"], max_retries: self.class::DEFAULT_MAX_RETRIES, timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS, initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY, max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY, idempotency_header: "Idempotency-Key") ⇒ Client

Creates and returns a new client for interacting with the API.

"https://api.example.com/v2/". Defaults to ENV["ORB_BASE_URL"]

Parameters:

  • api_key (String, nil) (defaults to: ENV["ORB_API_KEY"]) —

    Defaults to ENV["ORB_API_KEY"]

  • webhook_secret (String, nil) (defaults to: ENV["ORB_WEBHOOK_SECRET"]) —

    Defaults to ENV["ORB_WEBHOOK_SECRET"]

  • base_url (String, nil) (defaults to: ENV["ORB_BASE_URL"]) —

    Override the default base URL for the API, e.g.,

  • max_retries (Integer) (defaults to: self.class::DEFAULT_MAX_RETRIES) —

    Max number of retries to attempt after a failed retryable request.

  • timeout (Float) (defaults to: self.class::DEFAULT_TIMEOUT_IN_SECONDS)
  • initial_retry_delay (Float) (defaults to: self.class::DEFAULT_INITIAL_RETRY_DELAY)
  • max_retry_delay (Float) (defaults to: self.class::DEFAULT_MAX_RETRY_DELAY)
  • idempotency_header (String) (defaults to: "Idempotency-Key") 


183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/orb/client.rb', line 183

def initialize(
  api_key: ENV["ORB_API_KEY"],
  webhook_secret: ENV["ORB_WEBHOOK_SECRET"],
  base_url: ENV["ORB_BASE_URL"],
  max_retries: self.class::DEFAULT_MAX_RETRIES,
  timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
  initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
  max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY,
  idempotency_header: "Idempotency-Key"
)
  base_url ||= "https://api.withorb.com/v1"

  if api_key.nil?
    raise ArgumentError.new("api_key is required, and can be set via environ: \"ORB_API_KEY\"")
  end

  headers = {}
  custom_headers_env = ENV["ORB_CUSTOM_HEADERS"]
  unless custom_headers_env.nil?
    parsed = {}
    custom_headers_env.split("\n").each do |line|
      colon = line.index(":")
      unless colon.nil?
        parsed[line[0...colon].strip] = line[(colon + 1)..].strip
      end
    end
    headers = parsed.merge(headers)
  end

  @api_key = api_key.to_s
  @webhook_secret = webhook_secret&.to_s

  super(
    base_url: base_url,
    timeout: timeout,
    max_retries: max_retries,
    initial_retry_delay: initial_retry_delay,
    max_retry_delay: max_retry_delay,
    headers: headers,
    idempotency_header: idempotency_header
  )

  @webhooks = Orb::Resources::Webhooks.new(client: self)
  @top_level = Orb::Resources::TopLevel.new(client: self)
  @beta = Orb::Resources::Beta.new(client: self)
  @coupons = Orb::Resources::Coupons.new(client: self)
  @credit_notes = Orb::Resources::CreditNotes.new(client: self)
  @customers = Orb::Resources::Customers.new(client: self)
  @events = Orb::Resources::Events.new(client: self)
  @invoice_line_items = Orb::Resources::InvoiceLineItems.new(client: self)
  @invoices = Orb::Resources::Invoices.new(client: self)
  @items = Orb::Resources::Items.new(client: self)
  @metrics = Orb::Resources::Metrics.new(client: self)
  @plans = Orb::Resources::Plans.new(client: self)
  @prices = Orb::Resources::Prices.new(client: self)
  @subscriptions = Orb::Resources::Subscriptions.new(client: self)
  @alerts = Orb::Resources::Alerts.new(client: self)
  @dimensional_price_groups = Orb::Resources::DimensionalPriceGroups.new(client: self)
  @subscription_changes = Orb::Resources::SubscriptionChanges.new(client: self)
  @credit_blocks = Orb::Resources::CreditBlocks.new(client: self)
  @license_types = Orb::Resources::LicenseTypes.new(client: self)
  @licenses = Orb::Resources::Licenses.new(client: self)
end

Instance Attribute Details

#alerts ⇒ Orb::Resources::Alerts (readonly)

Alerts within Orb monitor spending, usage, or credit balance and trigger webhooks when a threshold is exceeded.

Alerts created through the API can be scoped to either customers or subscriptions.

Returns:



134
135
136
 
# File 'lib/orb/client.rb', line 134

def alerts
  @alerts
end

#api_key ⇒ String (readonly)

Returns:

  • (String) 


19
20
21
 
# File 'lib/orb/client.rb', line 19

def api_key
  @api_key
end

#beta ⇒ Orb::Resources::Beta (readonly)

The Plan resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the Price resource.

Returns:



35
36
37
 
# File 'lib/orb/client.rb', line 35

def beta
  @beta
end

#coupons ⇒ Orb::Resources::Coupons (readonly)

A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription. Coupons are activated using a redemption code, which applies the discount to a subscription or invoice. The duration of a coupon determines how long it remains available for use by end users.

Returns:



43
44
45
 
# File 'lib/orb/client.rb', line 43

def coupons
  @coupons
end

#credit_blocks ⇒ Orb::Resources::CreditBlocks (readonly)

The Credit Ledger Entry resource models prepaid credits within Orb.

Returns:



145
146
147
 
# File 'lib/orb/client.rb', line 145

def credit_blocks
  @credit_blocks
end

#credit_notes ⇒ Orb::Resources::CreditNotes (readonly)

The Credit Note resource represents a credit that has been applied to a particular invoice.

Returns:



48
49
50
 
# File 'lib/orb/client.rb', line 48

def credit_notes
  @credit_notes
end

#customers ⇒ Orb::Resources::Customers (readonly)

A customer is a buyer of your products, and the other party to the billing relationship.

In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an external_customer_id with your own identifier. See Customer ID Aliases for further information about how these aliases work in Orb.

In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the payment_provider_id and the payment_provider enum field to express this mapping.

A customer also has a timezone (from the standard IANA timezone database), which defaults to your account's timezone. See Timezone localization for information on what this timezone parameter influences within Orb.

Returns:



69
70
71
 
# File 'lib/orb/client.rb', line 69

def customers
  @customers
end

#dimensional_price_groups ⇒ Orb::Resources::DimensionalPriceGroups (readonly)

Returns:



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

def dimensional_price_groups
  @dimensional_price_groups
end

#events ⇒ Orb::Resources::Events (readonly)

The Event resource represents a usage event that has been created for a customer. Events are the core of Orb's usage-based billing model, and are used to calculate the usage charges for a given billing period.

Returns:



75
76
77
 
# File 'lib/orb/client.rb', line 75

def events
  @events
end

#invoice_line_items ⇒ Orb::Resources::InvoiceLineItems (readonly)

An Invoice is a fundamental billing entity, representing the request for payment for a single subscription. This includes a set of line items, which correspond to prices in the subscription's plan and can represent fixed recurring fees or usage-based fees. They are generated at the end of a billing period, or as the result of an action, such as a cancellation.

Returns:



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

def invoice_line_items
  @invoice_line_items
end

#invoices ⇒ Orb::Resources::Invoices (readonly)

An Invoice is a fundamental billing entity, representing the request for payment for a single subscription. This includes a set of line items, which correspond to prices in the subscription's plan and can represent fixed recurring fees or usage-based fees. They are generated at the end of a billing period, or as the result of an action, such as a cancellation.

Returns:



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

def invoices
  @invoices
end

#items ⇒ Orb::Resources::Items (readonly)

The Item resource represents a sellable product or good. Items are associated with all line items, billable metrics, and prices and are used for defining external sync behavior for invoices and tax calculation purposes.

Returns:



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

def items
  @items
end

#license_types ⇒ Orb::Resources::LicenseTypes (readonly)

The LicenseType resource represents a type of license that can be assigned to users. License types are used during billing by grouping metrics on the configured grouping key.

Returns:



151
152
153
 
# File 'lib/orb/client.rb', line 151

def license_types
  @license_types
end

#licenses ⇒ Orb::Resources::Licenses (readonly)

Returns:



154
155
156
 
# File 'lib/orb/client.rb', line 154

def licenses
  @licenses
end

#metrics ⇒ Orb::Resources::Metrics (readonly)

The Metric resource represents a calculation of a quantity based on events. Metrics are defined by the query that transforms raw usage events into meaningful values for your customers.

Returns:



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

def metrics
  @metrics
end

#plans ⇒ Orb::Resources::Plans (readonly)

The Plan resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the Price resource.

Returns:



110
111
112
 
# File 'lib/orb/client.rb', line 110

def plans
  @plans
end

#prices ⇒ Orb::Resources::Prices (readonly)

The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill.

Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present.

For more on the types of prices, see the core concepts documentation

Returns:



123
124
125
 
# File 'lib/orb/client.rb', line 123

def prices
  @prices
end

#subscription_changes ⇒ Orb::Resources::SubscriptionChanges (readonly)

Returns:



140
141
142
 
# File 'lib/orb/client.rb', line 140

def subscription_changes
  @subscription_changes
end

#subscriptions ⇒ Orb::Resources::Subscriptions (readonly)

Returns:



126
127
128
 
# File 'lib/orb/client.rb', line 126

def subscriptions
  @subscriptions
end

#top_level ⇒ Orb::Resources::TopLevel (readonly)

Returns:



28
29
30
 
# File 'lib/orb/client.rb', line 28

def top_level
  @top_level
end

#webhook_secret ⇒ String? (readonly)

Returns:

  • (String, nil) 


22
23
24
 
# File 'lib/orb/client.rb', line 22

def webhook_secret
  @webhook_secret
end

#webhooks ⇒ Orb::Resources::Webhooks (readonly)

Returns:



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

def webhooks
  @webhooks
end