defmodule Polymarket.Gamma do
  @moduledoc """
  Read-only wrappers for Polymarket's Gamma market-discovery API.

  All endpoints are public GETs against `Polymarket.Config.gamma_host/0`
  (`https://gamma-api.polymarket.com`). No authentication is required.

  ## Response shape and options

  All wrappers delegate to `Polymarket.HTTP.get/3`. See its `@moduledoc`
  for the response contract (`{:ok, body} | {:error, {:http_error, ...}} |
  {:error, {:transport_error, ...}}`) and the full per-call options list
  (`:host`, `:plug`, `:timeout`, `:retry`, `:max_retries`, `:headers`).

  GET requests default to Req's `:transient` retry policy; pass
  `retry: false` to disable.
  """

  @type result :: Polymarket.HTTP.result()

  @doc """
  Lists markets.

  Accepts caller-provided query params under the `:params` keyword option.
  Common Gamma filters include `:limit`, `:offset`, `:active`, `:closed`,
  `:archived`, `:order`, `:ascending`, `:conditionId`, `:slug`. This
  wrapper does not validate filter combinations.

  ## Examples

      Polymarket.Gamma.get_markets(
        params: [limit: 100, active: true, closed: false]
      )
  """
  @spec get_markets(keyword()) :: result()
  def get_markets(opts \\ []) do
    request(:get, "/markets", opts)
  end

  @doc """
  Gets a single market by its numeric Gamma **id**.

  This wrapper uses Gamma's path-segment lookup (`/markets/:id`), which
  accepts the numeric Gamma market id only. Passing a **slug** here
  returns `422 {"invalid integer"}` — the path segment is not a slug
  route. To look a market up by slug or conditionId, use `get_markets/1`
  with the corresponding query filter, e.g.
  `get_markets(params: [slug: "some-slug"])` or
  `get_markets(params: [conditionId: id])`.
  """
  @spec get_market(String.t() | integer(), keyword()) :: result()
  def get_market(id, opts \\ []) do
    request(:get, "/markets/#{id}", opts)
  end

  @doc """
  Lists events.

  Accepts caller-provided query params under `:params`. Polymarket events
  group related markets (one event can contain many YES/NO or multi-outcome
  markets). Common filters: `:limit`, `:offset`, `:active`, `:closed`,
  `:archived`, `:slug`.
  """
  @spec get_events(keyword()) :: result()
  def get_events(opts \\ []) do
    request(:get, "/events", opts)
  end

  @doc """
  Gets a single event by its numeric Gamma **id**.

  Like `get_market/2`, this uses Gamma's path-segment lookup
  (`/events/:id`), which accepts the numeric Gamma event id only —
  passing a **slug** returns `422 {"invalid integer"}`. To look an event
  up by slug, use `get_events/1` with `params: [slug: "some-slug"]`.
  """
  @spec get_event(String.t() | integer(), keyword()) :: result()
  def get_event(id, opts \\ []) do
    request(:get, "/events/#{id}", opts)
  end

  # ── Private ──

  defp request(:get, path, opts) do
    host = Keyword.get(opts, :host, Polymarket.Config.gamma_host())
    Polymarket.HTTP.get(host, path, Keyword.delete(opts, :host))
  end
end