@spec auth_link(TruelayerClient.t(), [auth_link_option()]) ::
  {:ok, String.t()} | {:error, TruelayerClient.Error.t()}

Generate an OAuth2 authorization URL to redirect the user to for bank login.

Options

• :scopes - list of OAuth2 scopes (required)
• :state - CSRF token (required — validate on redirect!)
• :nonce - replay-protection nonce
• :providers - whitelist of provider IDs shown to the user
• :enable_mock - show the TrueLayer mock bank in Sandbox

Example

{:ok, url} = TruelayerClient.Auth.auth_link(client,
  scopes: TruelayerClient.Auth.payments_scopes(),
  state: csrf_token
)
# Redirect user to url

@spec client_credentials(
  TruelayerClient.t(),
  [String.t()],
  TruelayerClient.Auth.Token.token_type()
) ::
  {:ok, TruelayerClient.Auth.Token.t()} | {:error, TruelayerClient.Error.t()}

Obtain a client-credentials token (server-to-server, no user interaction).

Results are cached in the token store. The cache is checked first; a new token is fetched only when the cached one has expired.

This is the primary token source for Payments, Payouts, and Mandates clients.

Example

{:ok, token} = TruelayerClient.Auth.client_credentials(
  client,
  TruelayerClient.Auth.payments_scopes(),
  :payments
)

@spec data_scopes() :: [String.t()]

Default scopes for Data API user-delegated calls.

@spec delete_credential(TruelayerClient.t(), String.t()) ::
  :ok | {:error, TruelayerClient.Error.t()}

Delete a stored credential (DELETE /connect/token/{credentials_id}).

Requires a valid Data-scoped token.

@spec exchange_code(
  TruelayerClient.t(),
  String.t(),
  TruelayerClient.Auth.Token.token_type()
) ::
  {:ok, TruelayerClient.Auth.Token.t()} | {:error, TruelayerClient.Error.t()}

Exchange an authorization code for an access token (POST /connect/token).

Call this in your OAuth2 redirect handler with the code from query params. The token is cached automatically in the configured store.

Example

def callback(conn, %{"code" => code, "state" => state}) do
  verify_csrf!(state)
  {:ok, token} = TruelayerClient.Auth.exchange_code(client, code, :payments)
  # Store token association with user session
end

@spec payments_scopes() :: [String.t()]

Default scopes for Payments API client-credentials calls.

@spec refresh_token(
  TruelayerClient.t(),
  String.t(),
  TruelayerClient.Auth.Token.token_type()
) ::
  {:ok, TruelayerClient.Auth.Token.t()} | {:error, TruelayerClient.Error.t()}

Refresh an access token using the stored refresh token.

Called automatically by valid_token/2 when the cached token is expired and has a refresh token available.

@spec valid_token(TruelayerClient.t(), TruelayerClient.Auth.Token.token_type()) ::
  {:ok, TruelayerClient.Auth.Token.t()} | {:error, TruelayerClient.Error.t()}

Return a valid, non-expired token for token_type.

If the stored token is expired and a refresh token is available, it is refreshed automatically. If no token is stored, returns {:error, ...}.

Used by Data API domain clients before each API call.