defmodule Solaris do
  @moduledoc """
  Production-grade Elixir client for the Solaris Embedded Finance API.

  See: https://docs.solarisgroup.com/api-reference

  ## Overview

  Solaris is a Banking-as-a-Service platform providing embedded finance APIs covering:

  - **Onboarding** — Create persons, businesses, KYC/identification flows
  - **Digital Banking** — Accounts, balances, bookings, statements, savings
  - **SEPA Transfers** — SCT, SDD, Instant payments
  - **Cards** — Issuance, lifecycle, tokenization, 3DS
  - **Lending** — Consumer loans, overdraft, splitpay, trade finance
  - **Webhooks** — Real-time event processing

  ## Configuration

      config :solaris,
        client_id: System.get_env("SOLARIS_CLIENT_ID"),
        client_secret: System.get_env("SOLARIS_CLIENT_SECRET"),
        environment: :sandbox,
        timeout: 30_000,
        max_retries: 3,
        pool_size: 10

  ## Quick Start

      {:ok, person} = Solaris.Onboarding.Persons.create(%{
        first_name: "Jane",
        last_name: "Doe",
        email: "jane@example.com",
        birth_date: ~D[1990-01-15],
        nationality: "DE"
      })

      {:ok, balance} = Solaris.Banking.Accounts.get_balance(account_id)

  ## Error Handling

  All functions return `{:ok, result}` or `{:error, %Solaris.Error{}}`.
  """

  alias Solaris.Client

  @spec version() :: String.t()
  def version, do: to_string(Application.spec(:solaris, :vsn))

  @spec environment() :: :sandbox | :production
  def environment, do: Solaris.Config.environment()

  @spec base_url() :: String.t()
  def base_url, do: Solaris.Config.base_url()

  @doc "Raw authenticated GET — for endpoints not yet covered by the SDK."
  @spec get(String.t(), keyword()) :: {:ok, map()} | {:error, Solaris.Error.t()}
  def get(path, opts \\ []), do: Client.get(path, opts)

  @doc "Raw authenticated POST."
  @spec post(String.t(), map(), keyword()) :: {:ok, map()} | {:error, Solaris.Error.t()}
  def post(path, body \\ %{}, opts \\ []), do: Client.post(path, body, opts)

  @doc "Raw authenticated PATCH."
  @spec patch(String.t(), map(), keyword()) :: {:ok, map()} | {:error, Solaris.Error.t()}
  def patch(path, body \\ %{}, opts \\ []), do: Client.patch(path, body, opts)

  @doc "Raw authenticated PUT."
  @spec put(String.t(), map(), keyword()) :: {:ok, map()} | {:error, Solaris.Error.t()}
  def put(path, body \\ %{}, opts \\ []), do: Client.put(path, body, opts)

  @doc "Raw authenticated DELETE."
  @spec delete(String.t(), keyword()) :: {:ok, map()} | {:error, Solaris.Error.t()}
  def delete(path, opts \\ []), do: Client.delete(path, opts)
end