defmodule Mercadopago do
  @moduledoc """
  Elixir client for Mercado Pago API.

  ## Configuration

  Add your Mercado Pago credentials to your application config:

      config :mercadopago,
        access_token: "YOUR_ACCESS_TOKEN",
        sandbox: true  # Set to false in production

  ## Usage

      # Create a payment
      {:ok, payment} = Mercadopago.Payment.create(%{
        transaction_amount: 100.0,
        token: "card_token",
        description: "Product description",
        payment_method_id: "visa",
        payer: %{email: "customer@email.com"}
      })

      # Using bang functions (raises on error)
      payment = Mercadopago.Payment.create!(%{...})

  ## Per-request configuration

  For multi-tenant applications, you can pass client options:

      Mercadopago.Payment.create(params, access_token: "tenant_token")

  Or create a client explicitly:

      client = Mercadopago.client(access_token: "tenant_token", sandbox: false)
      Mercadopago.Payment.create(params, client: client)

  ## Resources

  Available resource modules:

    * `Mercadopago.Resources.Payment` - Payment operations
    * `Mercadopago.Resources.Refund` - Refund operations
    * `Mercadopago.Resources.Customer` - Customer management
    * `Mercadopago.Resources.Card` - Saved cards
    * `Mercadopago.Resources.CardToken` - Card tokenization
    * `Mercadopago.Resources.Preference` - Checkout preferences
    * `Mercadopago.Resources.Subscription` - Recurring payments
    * `Mercadopago.Resources.PaymentMethod` - Available payment methods
    * `Mercadopago.Resources.IdentificationType` - ID types (RFC, CURP, etc.)
  """

  @doc """
  Creates a new client with the given options.

  Useful for multi-tenant applications where each tenant has different
  Mercado Pago credentials.

  ## Options

    * `:access_token` - Mercado Pago access token
    * `:sandbox` - Enable sandbox mode (default: from config)
    * `:base_url` - Override base URL
    * `:timeout` - Request timeout in milliseconds
    * `:recv_timeout` - Receive timeout in milliseconds

  ## Examples

      client = Mercadopago.client(access_token: "tenant_token")
      {:ok, payment} = Mercadopago.Payment.create(params, client: client)
  """
  @spec client(keyword()) :: Mercadopago.Client.t()
  def client(opts \\ []) do
    Mercadopago.Client.new(opts)
  end

  @doc """
  Returns the configured access token.
  """
  @spec access_token() :: String.t() | nil
  def access_token do
    Application.get_env(:mercadopago, :access_token)
  end

  @doc """
  Returns whether sandbox mode is enabled.
  """
  @spec sandbox?() :: boolean()
  def sandbox? do
    Application.get_env(:mercadopago, :sandbox, false)
  end
end