defmodule Bingex do
  @moduledoc ~S"""
  Bingex is an Elixir library for interacting with the BingX exchange, providing a transparent and reliable API interface.

  This library offers:
    - **HTTP API** for `Swap`, `Auth` and `Agent` scopes.
    - **Sockets API** for real-time WebSocket price updates and event streaming.
    - **Validated models** to ensure data reliability.
    - **Transparent request-response metadata**, exposing request-response metadata.

  ## Placing an Order

  To place an order on the BingX Swap market:

  ```elixir
  alias Bingex.{Model.Order, Swap}

  api_key = "YOUR_API_KEY"
  secret_key = "YOUR_SECRET_KEY"

  order = %Order{
    symbol: "BTC-USDT",
    side: :buy,
    type: :market,
    price: 65000,
    quantity: 0.01
  }

  case Swap.create_order(order, api_key, secret_key) do
    {:ok, response, _meta} -> IO.inspect(response, label: "Order Placed")
    {:error, error, _meta} -> IO.inspect(error, label: "Order Failed")
  end
  ```

  ## Fetching SWAP Balance

  To retrieve user balances:
  ```elixir
  alias Bingex.Swap

  case Swap.get_balance(api_key, secret_key) do
    {:ok, balance, _meta} -> IO.inspect(balance, label: "Account Balance")
    {:error, error, _meta} -> IO.inspect(error, label: "Balance Fetch Failed")
  end
  ```

  ## Sockets

  Define and start your WebSocket using Socket implementation (e.g. `Bingex.Swap.PriceSocket`):
  ```elixir
  defmodule PriceSource do
    use Bingex.Swap.PriceSocket
    alias Bingex.Swap.PriceSocket

    def start_link(_args \\ []) do
      PriceSocket.start_link(__MODULE__, :state)
    end

    @impl true
    def handle_connect(state) do
      PriceSocket.subscribe(symbol: "BTC-USDT", type: :last)
      {:ok, state}
    end

    @impl true
    def handle_event(type, event, state) do
      IO.inspect({type, event, state})
      {:ok, state}
    end
  end

  PriceSource.start_link()
  ```
  """
end