defmodule PolymarketClob do
  @moduledoc """
  Standalone Elixir client for the Polymarket CLOB API.

  This package owns the low-level CLOB surface only — auth, EIP-712 order
  signing, order placement, balances, order books, prices, and per-market
  metadata. Higher-level Polymarket features (Gamma market discovery, Data API
  normalization, RTDS, CTF, pUSD) are intentionally out of scope and live in
  separate packages.

  ## Layered API

  The recommended usage pattern is to call the API submodules directly. This
  module exposes only a small client-construction shorthand and a version
  helper; it intentionally does not shadow the layered API.

    * `PolymarketClob.Client` — client struct, address derivation, signature-type defaults.
    * `PolymarketClob.Config` — chain IDs, contract addresses, side and signature-type constants.
    * `PolymarketClob.API.MarketData` — public reads (markets, books, prices, fees, neg-risk, simplified/sampling lists, live activity).
    * `PolymarketClob.API.Account` — private reads (balances/allowances, orders, trades, scoring, notifications).
    * `PolymarketClob.API.Orders` — order placement and cancellation (POST/DELETE).
    * `PolymarketClob.Order.Builder` — local Python-parity amount calculation and signed-order construction.
    * `PolymarketClob.Order.Signing` — EIP-712 typed-data, order hash, and signature.
    * `PolymarketClob.Order.Rounding` — float-based rounding helpers ported from `py-clob-client-v2`.
    * `PolymarketClob.Auth.L1` — EIP-712 ClobAuth (with v2 `nonce`).
    * `PolymarketClob.Auth.L2` — HMAC-SHA256 request signing.
    * `PolymarketClob.HTTP` — Req-based transport layer (rarely called directly).
    * `PolymarketClob.Error` — normalized error struct returned by all API helpers.

  See `ENDPOINT_COVERAGE.md` for the full HTTP endpoint mapping against the
  audited `Polymarket/py-clob-client-v2` commit.

  ## Quick start

      client =
        PolymarketClob.client(
          private_key: System.fetch_env!("POLY_PRIVATE_KEY"),
          api_key: System.get_env("POLY_API_KEY"),
          api_secret: System.get_env("POLY_API_SECRET"),
          api_passphrase: System.get_env("POLY_API_PASSPHRASE")
        )

      {:ok, book} = PolymarketClob.API.MarketData.get_order_book("123456")
      {:ok, balance} = PolymarketClob.API.Account.get_balance_allowance(client)

  See `PolymarketClob.Client.new/1` for the full option list and signature-type
  auto-detection rules. With API credentials present, the client defaults to
  signature type `2` (Polymarket Gnosis Safe). Without them, it defaults to `0`
  (EOA).

  ## Parity with `py-clob-client-v2`

  Order amount calculation, EIP-712 signing, ClobAuth-with-nonce, and HMAC L2
  request signing are validated against deterministic fixtures generated from
  the official Python client. See `test/fixtures/parity/` and
  `scripts/generate_parity_fixtures.py`.
  """

  alias PolymarketClob.Client

  @doc """
  Returns the package version.

  Derived from the loaded application spec so it always tracks `mix.exs`.
  """
  @spec version() :: String.t()
  def version, do: Application.spec(:polymarket_clob, :vsn) |> to_string()

  @doc """
  Builds a `PolymarketClob.Client`.

  Convenience shorthand for `PolymarketClob.Client.new/1`. See that function
  for the full option list, address derivation, and signature-type defaults.
  """
  @spec client(keyword()) :: Client.t()
  def client(opts), do: Client.new(opts)
end