# `Parrhesia.Protocol`

Nostr protocol message decode/encode helpers.

This module is transport-oriented: it turns websocket payloads into structured tuples and
back again.

For programmatic API calls inside the application, prefer the `Parrhesia.API.*` modules.
In particular:

- `validate_event/1` returns user-facing error strings
- `Parrhesia.API.Auth.validate_event/1` returns machine-friendly validator atoms

# `client_message`

```elixir
@type client_message() ::
  {:event, event()}
  | {:req, String.t(), [filter()]}
  | {:close, String.t()}
  | {:auth, event()}
  | {:count, String.t(), [filter()], map()}
  | {:neg_open, String.t(), filter(), binary()}
  | {:neg_msg, String.t(), binary()}
  | {:neg_close, String.t()}
```

# `decode_error`

```elixir
@type decode_error() ::
  :invalid_json
  | :invalid_message
  | :invalid_event
  | :invalid_subscription_id
  | :invalid_filters
  | :invalid_auth
  | :invalid_count
  | :invalid_negentropy
```

# `event`

```elixir
@type event() :: map()
```

# `filter`

```elixir
@type filter() :: map()
```

# `relay_message`

```elixir
@type relay_message() ::
  {:notice, String.t()}
  | {:ok, String.t(), boolean(), String.t()}
  | {:closed, String.t(), String.t()}
  | {:eose, String.t()}
  | {:event, String.t(), event()}
  | {:auth, String.t()}
  | {:count, String.t(), map()}
  | {:neg_msg, String.t(), String.t()}
  | {:neg_err, String.t(), String.t()}
```

# `decode_client`

```elixir
@spec decode_client(binary()) :: {:ok, client_message()} | {:error, decode_error()}
```

Decodes a client websocket payload into a structured protocol tuple.

# `decode_error_notice`

```elixir
@spec decode_error_notice(decode_error()) :: String.t()
```

Converts a decode error into the relay notice string that should be sent to a client.

# `encode_relay`

```elixir
@spec encode_relay(relay_message()) :: binary()
```

Encodes a relay message tuple into the JSON frame sent to clients.

# `validate_event`

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

Validates an event and returns relay-facing error strings.

---

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