# `Parrhesia.API.Events`

Canonical event publish, query, and count API.

This is the main in-process API for working with Nostr events. It applies the same core
validation and policy checks used by the relay edge, but without going through a socket or
HTTP transport.

All public functions expect `opts[:context]` to contain a `Parrhesia.API.RequestContext`.
That context drives authorization, caller attribution, and downstream policy behavior.

`publish/2` intentionally returns `{:ok, %PublishResult{accepted: false}}` for policy and
storage rejections so callers can mirror relay `OK` semantics without treating a rejected
event as a process error.

# `count`

```elixir
@spec count(
  [map()],
  keyword()
) :: {:ok, non_neg_integer() | map()} | {:error, term()}
```

Counts events matching the given filters.

Required options:

- `:context` - a `Parrhesia.API.RequestContext`

Supported options:

- `:validate_filters?` - skips filter validation when `false`
- `:authorize_read?` - skips read policy checks when `false`
- `:options` - when set to a map, returns a NIP-45-style payload instead of a bare integer

When `opts[:options]` is a map, the result shape is `%{"count" => count, "approximate" => false}`.
If `opts[:options]["hll"]` is `true` and the feature is enabled, an `"hll"` field is included.

# `publish`

```elixir
@spec publish(
  map(),
  keyword()
) :: {:ok, Parrhesia.API.Events.PublishResult.t()} | {:error, term()}
```

Validates, authorizes, persists, and fans out an event.

Required options:

- `:context` - a `Parrhesia.API.RequestContext`

Supported options:

- `:max_event_bytes` - overrides the configured max encoded event size
- `:path`, `:private_key`, `:configured_private_key` - forwarded to the NIP-43 helper flow

Return semantics:

- `{:ok, %PublishResult{accepted: true}}` for accepted events
- `{:ok, %PublishResult{accepted: false}}` for rejected or duplicate events
- `{:error, :invalid_context}` only when the call itself is malformed

# `query`

```elixir
@spec query(
  [map()],
  keyword()
) :: {:ok, [map()]} | {:error, term()}
```

Queries stored events plus any dynamic NIP-43 events visible to the caller.

Required options:

- `:context` - a `Parrhesia.API.RequestContext`

Supported options:

- `:max_filter_limit` - overrides the configured per-filter limit
- `:validate_filters?` - skips filter validation when `false`
- `:authorize_read?` - skips read policy checks when `false`

The skip flags are primarily for internal composition, such as `Parrhesia.API.Stream`.
External callers should normally leave them enabled.

---

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