# `Urchin.JSONRPC`
[🔗](https://github.com/urth-inc/urchin/blob/v0.4.0/lib/urchin/jsonrpc.ex#L1)

Encoding, decoding and classification of JSON-RPC 2.0 messages.

The 2025-11-25 revision carries exactly one JSON-RPC message per transport frame
(HTTP request batching was removed), so this module operates on single messages.

Decoded messages are returned as tagged tuples so callers can branch on the kind
without re-inspecting the map:

  * `{:request, id, method, params}`
  * `{:notification, method, params}`
  * `{:response, id, result}`
  * `{:error_response, id, error}`

# `decoded`

```elixir
@type decoded() ::
  {:request, id(), String.t(), map()}
  | {:notification, String.t(), map()}
  | {:response, id(), term()}
  | {:error_response, id() | nil, map()}
```

# `id`

```elixir
@type id() :: String.t() | integer()
```

# `classify`

```elixir
@spec classify(term()) :: {:ok, decoded()} | {:error, Urchin.Error.t()}
```

Classifies an already-decoded JSON term (a map) into a tagged message.

Arrays are rejected: this revision does not support JSON-RPC batching.

# `decode`

```elixir
@spec decode(binary()) :: {:ok, decoded()} | {:error, Urchin.Error.t()}
```

Parses a JSON binary into a single classified JSON-RPC message.

Returns `{:ok, decoded}` or `{:error, Urchin.Error.t()}`. Malformed JSON yields a
parse error; structurally invalid messages yield an invalid-request error.

# `encode!`

```elixir
@spec encode!(map()) :: binary()
```

Encodes a message map to a JSON binary.

# `error_response`

```elixir
@spec error_response(id() | nil, Urchin.Error.t()) :: map()
```

Builds a JSON-RPC error response map. `id` may be nil for errors that cannot be
associated with a request (e.g. parse errors), serialized as JSON `null`.

# `notification`

```elixir
@spec notification(String.t(), map() | nil) :: map()
```

Builds a JSON-RPC notification map.

# `request`

```elixir
@spec request(id(), String.t(), map() | nil) :: map()
```

Builds a JSON-RPC request map.

# `result`

```elixir
@spec result(id(), term()) :: map()
```

Builds a successful JSON-RPC response map.

---

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