revolut_client

defmodule RevolutClient do
  @moduledoc """
  `RevolutClient` — Production-grade Elixir SDK for the complete Revolut Developer API.

  ## Supported APIs

  | Module | Description |
  |--------|-------------|
  | `RevolutClient.Merchant` | Orders, customers, subscriptions, disputes, payouts |
  | `RevolutClient.Business` | Accounts, payments, cards, team members |
  | `RevolutClient.OpenBanking` | AISP + PISP (OB v3.1) |
  | `RevolutClient.CryptoRamp` | Fiat ↔ crypto on-ramp partner API |
  | `RevolutClient.CryptoExchange` | Revolut X trading API |
  | `RevolutClient.Webhook` | Signature verification + event dispatch |

  ## Quickstart

      # Build a config
      config = RevolutClient.Config.new!(api_key: System.fetch_env!("REVOLUT_MERCHANT_KEY"))

      # Instantiate a client
      merchant = RevolutClient.merchant(config)

      # Make a call
      {:ok, order} = RevolutClient.Merchant.create_order(merchant, %{
        amount: 1000,
        currency: "GBP",
        description: "Widget"
      })

  ## Sandbox / production

      sandbox_config = RevolutClient.Config.sandbox!("sk_sandbox_...")
      prod_config    = RevolutClient.Config.prod!("sk_live_...")

  ## Configuration via `config.exs`

      config :revolut_client,
        environment: :sandbox,
        timeout_ms: 15_000,
        max_attempts: 2

  Per-client options always override application-level defaults.

  ## Error handling

  Every function returns `{:ok, result}` or `{:error, RevolutClient.Error.t()}`.
  Pattern-match on the error struct type for precise error handling:

      case RevolutClient.Merchant.get_order(client, id) do
        {:ok, order}                                   -> handle(order)
        {:error, %RevolutClient.Error.API{status_code: 404}} -> not_found()
        {:error, %RevolutClient.Error.API{retryable?: true}}  -> retry()
        {:error, %RevolutClient.Error.Network{}}              -> retry()
        {:error, err}                                  -> raise err
      end

  ## Telemetry

  All HTTP calls emit telemetry events under the configured prefix
  (default `[:revolut_client, :request]`):

      :telemetry.attach("revolut-logger", [:revolut_client, :request, :stop], fn event, measurements, metadata, _ ->
        Logger.info("Revolut \#{metadata.method} \#{metadata.url} -> \#{metadata.status} in \#{measurements.duration}ns")
      end, nil)
  """

  alias RevolutClient.Config

  # ---------------------------------------------------------------------------
  # Convenience constructors
  # ---------------------------------------------------------------------------

  @doc "Create a `RevolutClient.Merchant` client from a `Config`."
  @spec merchant(Config.t()) :: RevolutClient.Merchant.t()
  defdelegate merchant(config), to: RevolutClient.Merchant, as: :new

  @doc "Create a `RevolutClient.Business` client from a `Config`."
  @spec business(Config.t()) :: RevolutClient.Business.t()
  defdelegate business(config), to: RevolutClient.Business, as: :new

  @doc "Create a `RevolutClient.OpenBanking` client from a `Config`."
  @spec open_banking(Config.t()) :: RevolutClient.OpenBanking.t()
  defdelegate open_banking(config), to: RevolutClient.OpenBanking, as: :new

  @doc "Create a `RevolutClient.CryptoRamp` client from a `Config`."
  @spec crypto_ramp(Config.t()) :: RevolutClient.CryptoRamp.t()
  defdelegate crypto_ramp(config), to: RevolutClient.CryptoRamp, as: :new

  @doc "Create a `RevolutClient.CryptoExchange` client from a `Config`."
  @spec crypto_exchange(Config.t()) :: RevolutClient.CryptoExchange.t()
  defdelegate crypto_exchange(config), to: RevolutClient.CryptoExchange, as: :new
end