Triple.Config (triple v1.0.0)

Copy Markdown View Source

Configuration for a Triple client.

A %Triple.Config{} struct is the client — it's plain data, holds no open connections or processes, and is passed explicitly to every call (Triple.enrich_transaction(client, ...), etc). This makes it safe to build multiple clients (e.g. one per tenant, or one for sandbox + one for production) in the same application without any global or process-dictionary state.

Creating a client

client = Triple.Config.new(api_key: "tr_live_xxx")

Or, equivalently, via the top-level shortcut:

client = Triple.new(api_key: "tr_live_xxx")

Application-wide defaults

Any option can also be set application-wide and will be used whenever it isn't passed explicitly to new/1:

config :triple,
  api_key: System.fetch_env!("TRIPLE_API_KEY"),
  receive_timeout: 15_000

Options

  • :api_key (required) — your Triple API key. Keys starting with tr_test_ are sandbox keys, tr_live_ are production keys.
  • :environment — :production or :sandbox. If omitted, it's inferred from the :api_key prefix.
  • :base_url — override the API host. Defaults to Triple's production or sandbox URL based on :environment.
  • :control_base_url — override the control-plane host (currently only used by Triple.TLS). Defaults similarly based on :environment.
  • :receive_timeout — response timeout in ms. Default 30_000.
  • :connect_timeout — connection timeout in ms. Default 5_000.
  • :retry — retry strategy. :default (the default) retries 408/429/500/502/503/504 and transport errors with exponential backoff, honoring the retry-after header on 429s. Also accepts false, Req's own built-in :transient / :safe_transient, or a custom 2-arity function — see Req's :retry option for the exact contract.
  • :max_retries — maximum retry attempts. Default 3.
  • :rate_limiter — optionally, the name/pid of a running Triple.RateLimiter to throttle outgoing requests client-side. Default nil (disabled).
  • :req_options — a keyword list merged into the underlying Req.new/1 call, for anything not covered above (custom steps, a :plug for testing, etc). Takes precedence over this module's own defaults.

Summary

Types

environment()
retry_strategy()
t()

Functions

infer_environment!(arg1)

Infers :production or :sandbox from an API key's prefix (tr_live_ / tr_test_). Raises ArgumentError if the key matches neither — pass :environment explicitly in that case.

new(opts \\ [])

Builds a new client config, raising ArgumentError if no :api_key can be found (either passed explicitly or set via config :triple, ...).

Types

environment()

@type environment() :: :production | :sandbox

retry_strategy()

@type retry_strategy() ::
  :default
  | :transient
  | :safe_transient
  | false
  | (Req.Request.t(), Req.Response.t() | Exception.t() ->
       boolean() | {:delay, non_neg_integer()})

t()

@type t() :: %Triple.Config{
  api_key: String.t(),
  base_url: String.t(),
  connect_timeout: pos_integer(),
  control_base_url: String.t(),
  environment: environment(),
  max_retries: non_neg_integer(),
  rate_limiter: GenServer.name() | pid() | nil,
  receive_timeout: pos_integer(),
  req_options: keyword(),
  retry: retry_strategy()
}

Functions

infer_environment!(arg1)

@spec infer_environment!(String.t()) :: environment()

Infers :production or :sandbox from an API key's prefix (tr_live_ / tr_test_). Raises ArgumentError if the key matches neither — pass :environment explicitly in that case.

new(opts \\ [])

@spec new(keyword()) :: t()

Builds a new client config, raising ArgumentError if no :api_key can be found (either passed explicitly or set via config :triple, ...).