defmodule Mercury do
  @moduledoc """
  A complete, production-grade Elixir client for the [Mercury Banking
  API](https://docs.mercury.com/reference).

  ## Installation

      def deps do
        [{:mercury, "~> 0.1"}]
      end

  ## Quick start

      client = Mercury.Client.new("secret-token:mercury_production_...")

      {:ok, %Mercury.Page{items: accounts}} = Mercury.Accounts.list(client)

      {:ok, account} = Mercury.Accounts.get(client, "account-id")

      # Auto-paginating, lazy stream across every page:
      client
      |> Mercury.Accounts.stream()
      |> Enum.each(&IO.inspect/1)

  Every read/write function returns `{:ok, result}` or `{:error, exception}`.
  A `!`-suffixed variant is also available on every function and raises the
  exception instead (e.g. `Mercury.Accounts.get!/2`).

  ## Configuration

  `Mercury.Client.new/2` accepts:

    * `:base_url` — override the API base URL (useful for sandboxes). Defaults
      to `"https://api.mercury.com/api/v1"`.
    * `:timeout` — per-request timeout in milliseconds. Defaults to `30_000`.
    * `:retry` — a `Mercury.Retry` struct controlling retry behaviour for
      transient failures. Defaults to `Mercury.Retry.default/0`.
    * `:on_request` — a 3-arity function `(method, url, request_id -> any)`
      called before each request is sent.
    * `:on_response` — a 5-arity function
      `(method, url, request_id, status, duration_ms -> any)` called after
      each response is received.
    * `:req_options` — a keyword list merged into the underlying `Req.new/1`
      call, for full escape-hatch control (custom `Finch` pool, plugs for
      testing, proxies, etc).

  ## Errors

  All API errors are raised/returned as one of the exception structs under
  `Mercury.*Error` (see `Mercury.Error` for classification predicates like
  `Mercury.Error.rate_limit_error?/1`).

  ## Pagination

  Every list endpoint has three matching functions:

    * `list/2` — fetch a single page as a `Mercury.Page` struct.
    * `stream/2` — a lazy `Stream` of individual items across every page,
      built with `Mercury.Pagination.stream/1`. Combine with `Enum.take/2`,
      `Stream.take_while/2`, or `Enum.to_list/1` as needed.

  ## Webhooks

  `Mercury.Webhooks.verify_signature/3` validates the `Mercury-Signature`
  header on incoming webhook deliveries using constant-time HMAC comparison.
  """

  @version "1.0.0"
  @sdk_version "mercury-elixir/#{@version}"

  @doc "Returns the version of this SDK."
  @spec version() :: String.t()
  def version, do: @version

  @doc false
  @spec sdk_version() :: String.t()
  def sdk_version, do: @sdk_version
end