defmodule ApiBrasil.Platform.Catalog do
  @moduledoc """
  Catálogo público da plataforma: APIs, planos, documentações e servidores.

  A maioria das rotas é pública — não exige Bearer Token.

      alias ApiBrasil.Platform.Catalog

      {:ok, resultado} = Catalog.apis(client, "whatsapp")
      {:ok, planos} = Catalog.plans(client)
  """

  use ApiBrasil.Core.Service

  @doc """
  Lista/busca as APIs disponíveis: `GET /apis?search=`.

  `search` é opcional: `nil` (ou string vazia) lista o catálogo inteiro.
  """
  @spec apis(Client.t(), String.t() | nil, keyword()) :: result()
  def apis(client, search \\ nil, opts \\ []) do
    if search in [nil, ""] do
      Service.get(client, "apis", opts)
    else
      Service.get_query(client, "apis", %{"search" => search}, opts)
    end
  end

  @doc "Como `apis/3`, mas levanta `ApiBrasil.Core.Error` em caso de falha."
  @spec apis!(Client.t(), String.t() | nil, keyword()) :: map()
  def apis!(client, search \\ nil, opts \\ []) do
    Service.unwrap!(apis(client, search, opts))
  end

  @doc "Detalha uma API por identificador: `GET /apis/{identifier}`."
  @spec api(Client.t(), String.t(), keyword()) :: result()
  def api(client, identifier, opts \\ []) do
    Service.get(client, "apis/#{Service.encode_path(identifier)}", opts)
  end

  @doc "Como `api/3`, mas levanta `ApiBrasil.Core.Error` em caso de falha."
  @spec api!(Client.t(), String.t(), keyword()) :: map()
  def api!(client, identifier, opts \\ []) do
    Service.unwrap!(api(client, identifier, opts))
  end

  @doc "Detalha uma API pelo nome: `GET /apis/name/{name}`."
  @spec api_by_name(Client.t(), String.t(), keyword()) :: result()
  def api_by_name(client, name, opts \\ []) do
    Service.get(client, "apis/name/#{Service.encode_path(name)}", opts)
  end

  @doc "Como `api_by_name/3`, mas levanta `ApiBrasil.Core.Error` em caso de falha."
  @spec api_by_name!(Client.t(), String.t(), keyword()) :: map()
  def api_by_name!(client, name, opts \\ []) do
    Service.unwrap!(api_by_name(client, name, opts))
  end

  @doc "Lista as APIs vinculadas a um device: `GET /apis/device/{device_token}`."
  @spec apis_by_device(Client.t(), String.t(), keyword()) :: result()
  def apis_by_device(client, device_token, opts \\ []) do
    Service.get(client, "apis/device/#{Service.encode_path(device_token)}", opts)
  end

  @doc "Como `apis_by_device/3`, mas levanta `ApiBrasil.Core.Error` em caso de falha."
  @spec apis_by_device!(Client.t(), String.t(), keyword()) :: map()
  def apis_by_device!(client, device_token, opts \\ []) do
    Service.unwrap!(apis_by_device(client, device_token, opts))
  end

  @doc "Documentação por servidor: `GET /documentations/server/{server_search}`."
  @spec documentations_by_server(Client.t(), String.t(), keyword()) :: result()
  def documentations_by_server(client, server_search, opts \\ []) do
    Service.get(client, "documentations/server/#{Service.encode_path(server_search)}", opts)
  end

  @doc """
  Como `documentations_by_server/3`, mas levanta `ApiBrasil.Core.Error` em
  caso de falha.
  """
  @spec documentations_by_server!(Client.t(), String.t(), keyword()) :: map()
  def documentations_by_server!(client, server_search, opts \\ []) do
    Service.unwrap!(documentations_by_server(client, server_search, opts))
  end

  route_get(
    :api_categories,
    "apis/categories",
    "Lista as categorias de APIs: `GET /apis/categories`."
  )

  route_get(
    :my_apis,
    "apis/list",
    "Lista as APIs contratadas pelo usuário (autenticado): `GET /apis/list`."
  )

  route_get(:plans, "plans", "Lista os planos disponíveis: `GET /plans`.")

  route_get(:documentations, "documentations", "Lista as documentações: `GET /documentations`.")

  route_get(:servers, "servers", "Lista os servidores disponíveis: `GET /servers`.")

  route_get(:status, "status", "Status do gateway: `GET /status`.")

  route_post(
    :endpoint_url,
    "endpoint/url",
    "Resolve a URL de uma action (descoberta dinâmica de endpoints): `POST /endpoint/url`."
  )

  route_post(
    :endpoint_body,
    "endpoint/body",
    "Body esperado por uma action: `POST /endpoint/body`."
  )
end