Parrhesia.API.Events (parrhesia v0.12.0)

Copy Markdown

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.

Summary

Functions

count(filters, opts \\ [])

Counts events matching the given filters.

publish(event, opts \\ [])

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

query(filters, opts \\ [])

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

Functions

count(filters, opts \\ [])

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

Counts events matching the given filters.

Required options:

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(event, opts \\ [])

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

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

Required options:

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(filters, opts \\ [])

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

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

Required options:

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.