# `Cauldron2D.Net.Remote`
[🔗](https://github.com/jaman/cauldron/blob/v0.1.3/cauldron_2d_net/lib/cauldron_2d/net/remote.ex#L1)

What a client asks a server it does not run in: a token for a name and password over
HTTP (`Cauldron2D.Net.Api`), the arenas, the server's stats and boards; and the same
from a node it is connected to.

    {:ok, token} = Cauldron2D.Net.Remote.login("http://arcade:2280", "alice", "secret", false)
    {:ok, arenas} = Cauldron2D.Net.Remote.arenas("http://arcade:2280")
    {:ok, arenas} = Cauldron2D.Net.Remote.node_arenas(:"my_game@arcade")
    {:ok, world} = Cauldron2D.Net.Remote.node_world(:"my_game@arcade", :pit)

`url` is the server's base URL with the API's path, `http://host:port/api` for an
API forwarded at `/api`.

# `arena`

```elixir
@type arena() :: %{
  id: String.t(),
  name: String.t(),
  map: String.t() | nil,
  note: String.t() | nil,
  players: non_neg_integer(),
  teams: list(),
  kind: {String.t(), {byte(), byte(), byte()}} | nil
}
```

# `arenas`

```elixir
@spec arenas(String.t()) :: {:ok, [arena()]} | {:error, String.t()}
```

The arenas from `GET <url>/arenas`.

# `leaders`

```elixir
@spec leaders(String.t(), atom(), atom(), keyword()) ::
  {:ok, [map()]} | {:error, String.t()}
```

A board from `GET <url>/leaders`, as `Cauldron2D.Ledger.board/4` gives it, accounts as strings.

# `login`

```elixir
@spec login(String.t(), String.t(), String.t(), boolean()) ::
  {:ok, String.t()} | {:error, String.t()}
```

A token from `POST <url>/token`; `register?` makes the account first. `{:error, text}` with the server's reason.

# `node_arenas`

```elixir
@spec node_arenas(node()) :: {:ok, [map()]} | {:error, String.t()}
```

The arenas of a connected node, as its `Cauldron2D.Arenas.list/0` gives them.

# `node_leaders`

```elixir
@spec node_leaders(node(), GenServer.name(), atom(), atom(), keyword()) ::
  {:ok, [map()]} | {:error, String.t()}
```

A board of a connected node's ledger.

# `node_world`

```elixir
@spec node_world(node(), term()) :: {:ok, pid()} | {:error, String.t()}
```

The pid of arena `id`'s world on `node`, started there if it was not running.

# `stats`

```elixir
@spec stats(String.t()) ::
  {:ok, %{arenas: [map()], node: map()}} | {:error, String.t()}
```

How the server is keeping up, from `GET <url>/stats`, with atom keys.

---

*Consult [api-reference.md](api-reference.md) for complete listing*