Ramp.Client (ramp v1.0.0)

Holds the resolved configuration for talking to the Ramp API: base URL, HTTP/retry tuning, telemetry prefix, and the pid/name of the Ramp.TokenManager that supplies bearer tokens.

A %Ramp.Client{} is an immutable, plain struct -- cheap to build and safe to share across processes. All the actual mutable state (the cached OAuth2 token) lives in the Ramp.TokenManager process it points to.

Summary

Types

new_opt()

t()

Functions

default_base_url()

The production Ramp API base URL.

exchange_auth_code(client, code, redirect_uri)

Exchanges an OAuth2 authorization code for an access token, for the partner / multi-tenant authorization_code flow.

new(opts)

Builds a new Ramp.Client.

refresh_token(client)

Forces an immediate token refresh on the client's token manager, bypassing the cache. Rarely needed -- Ramp.HTTP already refreshes automatically on a 401 response.

sandbox_base_url()

The Ramp sandbox API base URL, for integration testing without real money movement.

stop(client)

Stops a client's token manager, if the client started/owns it (i.e. was not built with an externally supervised :token_manager). Safe to call even if the client doesn't own its token manager (it's a no-op).

Types

new_opt()

@type new_opt() ::
  {:client_id, String.t()}
  | {:client_secret, String.t()}
  | {:scopes, [String.t()]}
  | {:base_url, String.t()}
  | {:sandbox, boolean()}
  | {:http_timeout_ms, pos_integer()}
  | {:max_retries, non_neg_integer()}
  | {:retry_base_delay_ms, pos_integer()}
  | {:access_token, String.t()}
  | {:token_manager, GenServer.server()}

t()

@type t() :: %Ramp.Client{
  base_url: String.t(),
  http_timeout_ms: pos_integer(),
  max_retries: non_neg_integer(),
  owns_token_manager?: boolean(),
  retry_base_delay_ms: pos_integer(),
  token_manager: GenServer.server()
}

Functions

default_base_url()

@spec default_base_url() :: String.t()

The production Ramp API base URL.

exchange_auth_code(client, code, redirect_uri)

@spec exchange_auth_code(t(), String.t(), String.t()) ::
  {:ok, String.t()} | {:error, Ramp.Error.t()}

Exchanges an OAuth2 authorization code for an access token, for the partner / multi-tenant authorization_code flow.

new(opts)

@spec new([new_opt()]) :: t()

Builds a new Ramp.Client.

There are three ways to authenticate:

client_credentials (recommended, default) -- pass :client_id and :client_secret. An unsupervised Ramp.TokenManager is started and linked to the calling process; it fetches and refreshes tokens automatically.
Pre-obtained access token -- pass :access_token (and optionally :expires_in, defaulting to a generous 10 days). Useful for CLI tools or when you manage token storage/refresh yourself.
Externally supervised TokenManager -- pass :token_manager with the pid/name of a Ramp.TokenManager you started yourself in your supervision tree (see Ramp.TokenManager). This is the recommended approach for long-running production applications.

Options

:client_id, :client_secret - OAuth2 client credentials
:scopes - list of OAuth2 scope strings, e.g. ~w(transactions:read cards:read)
:base_url - overrides the default production API URL
:sandbox - if true, uses the sandbox base URL (ignored if :base_url given)
:http_timeout_ms - per-request timeout, default 30_000
:max_retries - max retry attempts on transient errors, default 3
:retry_base_delay_ms - exponential backoff base delay, default 500
:access_token / :expires_in - use a pre-obtained token instead of client_id/client_secret
:token_manager - use an externally supervised Ramp.TokenManager instead of starting one

Examples

client =
  Ramp.Client.new(
    client_id: System.fetch_env!("RAMP_CLIENT_ID"),
    client_secret: System.fetch_env!("RAMP_CLIENT_SECRET"),
    scopes: ~w(transactions:read cards:read users:read)
  )

{:ok, card} = Ramp.Cards.get(client, "crd_123")

refresh_token(client)

@spec refresh_token(t()) :: {:ok, String.t()} | {:error, Ramp.Error.t()}

Forces an immediate token refresh on the client's token manager, bypassing the cache. Rarely needed -- Ramp.HTTP already refreshes automatically on a 401 response.

sandbox_base_url()

@spec sandbox_base_url() :: String.t()

The Ramp sandbox API base URL, for integration testing without real money movement.

stop(client)

@spec stop(t()) :: :ok

Stops a client's token manager, if the client started/owns it (i.e. was not built with an externally supervised :token_manager). Safe to call even if the client doesn't own its token manager (it's a no-op).