PlaidEx.Config (plaid_ex v1.0.0)

Validated runtime configuration for PlaidEx.

Supports three configuration patterns:

1. Application config (compile-time / release config)

# config/config.exs
config :plaid_ex,
  client_id: System.get_env("PLAID_CLIENT_ID"),
  secret: System.get_env("PLAID_SECRET"),
  environment: :sandbox

2. Runtime struct construction (for multi-tenant / secrets managers)

config = PlaidEx.Config.new!(
  client_id: vault.get("plaid/client_id"),
  secret: vault.get("plaid/secret"),
  environment: :production,
  tenant_id: "acme_corp"
)

3. Dynamic per-call overrides

PlaidEx.API.Transactions.sync(config, access_token: "access-...")

Regions

Plaid routes to different base URLs based on region:

:us → production.plaid.com / sandbox.plaid.com
:eu → production.eu.plaid.com
:uk → alias for :eu (same EU infrastructure)

Environments

:sandbox — Plaid sandbox (test data, no real bank connections)
:development — Plaid development (real bank connections, limited items)
:production — Plaid production (real bank connections, full capacity)

Summary

Types

environment()

region()

t()

Functions

api_version()

Returns the Plaid API version header value.

base_url(config)

Returns the Plaid API base URL for the given config.

load!()

Loads config from the application environment.

new!(opts)

Builds a validated PlaidEx.Config from a keyword list.

production?(config)

Returns true if this config targets a live (non-sandbox) environment. Use this to gate production-only safety checks.

rotate_secret(config, new_secret)

Returns a new config with the secret replaced. Useful for secret rotation without recreating the full config.

scrub(config)

Returns a scrubbed version of the config safe for logging. Replaces the secret with a redacted placeholder.

Types

environment()

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

region()

@type region() :: :us | :eu | :uk

t()

@type t() :: %PlaidEx.Config{
  cache_institutions_ttl_ms: pos_integer(),
  circuit_breaker_reset_ms: pos_integer(),
  circuit_breaker_threshold: pos_integer(),
  client_id: String.t(),
  connect_timeout_ms: pos_integer(),
  environment: environment(),
  metadata: map(),
  oban_max_attempts: pos_integer(),
  oban_queue: atom(),
  pool_count: pos_integer(),
  pool_size: pos_integer(),
  region: region(),
  request_timeout_ms: pos_integer(),
  retry_base_delay_ms: pos_integer(),
  retry_max_attempts: non_neg_integer(),
  retry_max_delay_ms: pos_integer(),
  secret: String.t(),
  sync_poll_interval_ms: pos_integer(),
  telemetry_prefix: [atom()],
  tenant_id: String.t() | nil,
  webhook_secret: String.t() | nil
}

Functions

api_version()

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

Returns the Plaid API version header value.

base_url(config)

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

Returns the Plaid API base URL for the given config.

Examples

iex> PlaidEx.Config.base_url(%PlaidEx.Config{environment: :sandbox, region: :us})
"https://sandbox.plaid.com"

iex> PlaidEx.Config.base_url(%PlaidEx.Config{environment: :production, region: :eu})
"https://production.eu.plaid.com"

load!()

@spec load!() :: t()

Loads config from the application environment.

Reads from Application.get_all_env(:plaid_ex) and validates. Raises on missing required keys or invalid values.

Call this once at application start, not on every request.

new!(opts)

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

Builds a validated PlaidEx.Config from a keyword list.

Raises ArgumentError on validation failure.

Example

config = PlaidEx.Config.new!(
  client_id: "your-client-id",
  secret: "your-secret",
  environment: :production,
  region: :us,
  pool_size: 50
)

production?(config)

@spec production?(t()) :: boolean()

Returns true if this config targets a live (non-sandbox) environment. Use this to gate production-only safety checks.

rotate_secret(config, new_secret)

@spec rotate_secret(t(), String.t()) :: t()

Returns a new config with the secret replaced. Useful for secret rotation without recreating the full config.

scrub(config)

@spec scrub(t()) :: map()

Returns a scrubbed version of the config safe for logging. Replaces the secret with a redacted placeholder.