defmodule Nombaone do
  @moduledoc """
  The official Elixir SDK for the [Nomba One](https://nombaone.xyz)
  subscription-billing API.

  Recurring billing for Nigeria over card, direct debit, and bank transfer,
  with dunning that recovers and a ledger that never loses a kobo.

  > #### Sandbox first {: .tip}
  >
  > Grab a sandbox key (`nbo_sandbox_…`) from the dashboard, and you are three
  > objects away from a live subscription. The sandbox runs the real billing
  > engine — see `Nombaone.Sandbox`.

  ## Quickstart

      client = Nombaone.new("nbo_sandbox_…")

      {:ok, customer} = Nombaone.Customers.create(client, %{
        email: "ada@example.com",
        name: "Ada Lovelace"
      })

  Every resource method returns `{:ok, result}` or `{:error, %Nombaone.Error{}}`,
  and has a raising `!` variant (e.g. `Nombaone.Customers.create!/2`).
  """

  # Baked in at compile time — `Mix.Project` is not available at runtime.
  @version Mix.Project.config()[:version]

  @doc """
  Build a client. Delegates to `Nombaone.Client.new/2`; see that module for the
  full option list.

      client = Nombaone.new("nbo_sandbox_…", timeout: 10_000)

  With no key, the `NOMBAONE_API_KEY` environment variable is used:

      client = Nombaone.new()
  """
  @spec new(String.t() | keyword(), keyword()) :: Nombaone.Client.t()
  def new(api_key_or_options \\ [], options \\ []),
    do: Nombaone.Client.new(api_key_or_options, options)

  @doc """
  The SDK version, as published to Hex.
  """
  @spec version() :: String.t()
  def version, do: @version
end