defmodule SetuClient do
  @moduledoc """
  Production-grade Elixir client for the [Setu API Platform](https://docs.setu.co).

  ## Quick start

      # config/config.exs
      config :setu,
        client_id: System.get_env("SETU_CLIENT_ID"),
        client_secret: System.get_env("SETU_CLIENT_SECRET"),
        product_instance_id: System.get_env("SETU_PRODUCT_INSTANCE_ID"),
        environment: :sandbox

      # In application code
      cfg = SetuClient.config()

      {:ok, qr} = SetuClient.Payments.UPI.create_dqr(cfg, merchant_id, %{
        merchant_vpa: "shop@pineaxis",
        amount: 10_000
      })

  ## Module index

  | Module | Purpose |
  |--------|---------|
  | `SetuClient.Payments.UPI` | Flash/DQR/SQR, Collect, TPV, Mandates, Refunds, Disputes, Onboarding |
  | `SetuClient.Payments.BBPS` | BillCollect biller-side helpers |
  | `SetuClient.Payments.BillPay` | BBPS agent bill payment |
  | `SetuClient.Payments.WhatsApp` | WhatsApp Collect reminders |
  | `SetuClient.Data.AA` | Account Aggregator FIU — consent + data fetch |
  | `SetuClient.Data.KYC.PAN` | PAN verification (NSDL) |
  | `SetuClient.Data.KYC.BAV` | Bank account verification (penny-drop) |
  | `SetuClient.Data.KYC.GST` | GSTIN verification |
  | `SetuClient.Data.KYC.NameMatch` | Optimistic + pessimistic name matching |
  | `SetuClient.Data.KYC.EKYC` | Aadhaar eKYC |
  | `SetuClient.Data.KYC.DigiLocker` | DigiLocker session + document fetch |
  | `SetuClient.Data.ESign` | Aadhaar eSign (up to 6 signers) |
  | `SetuClient.Webhook.Handler` | Dispatcher for all 25+ event types |
  | `SetuClient.Webhook.Callbacks` | Behaviour + `use` macro with defaults |
  | `SetuClient.Config` | Configuration struct and helpers |
  | `SetuClient.Error` | Structured error type |
  | `SetuClient.Validation` | Shared client-side validation helpers |
  """

  alias SetuClient.Config

  @doc "Returns a `SetuClient.Config` populated from application config."
  @spec config() :: Config.t()
  def config, do: Config.new([])

  @doc "Returns a `SetuClient.Config` from application config merged with keyword overrides."
  @spec config(keyword()) :: Config.t()
  def config(overrides), do: Config.new(overrides)

  @doc "Returns the SDK version string."
  @spec version() :: String.t()
  def version, do: to_string(Application.spec(:setu, :vsn))
end