@spec cancel(query_ref()) :: :ok | {:error, :not_found}

Cancels a streaming query.

Examples

iex> {:ok, ref} = Nostr.Client.stream(["wss://relay.example.com"], %{kinds: [1]})
iex> Nostr.Client.cancel(ref)
:ok

@spec fetch([relay_uri()], filter(), Keyword.t()) ::
  {:ok, [event()]} | {:error, term()}

Fetches events from the specified relays using the given filter.

This is a blocking call that waits for either:

• EOSE from every relay, or
• idle timeout after subscriptions are started (default: 5000ms)

Options

• :idle_ms - inactivity window in milliseconds after REQs are sent (default: 5000)
• :overall_timeout - hard stop timeout in milliseconds (default: 30_000)
• :cache? - enable/disable caching (default: true)
• :dedup_strategy - deduplication strategy module (default: Nostr.Dedup.Default)
• :paginate - when true, perform repeated queries decreasing :until until no more events are returned or global limit reached (default: false)
• :paginate_global_limit - total number of events to return across all pages; defaults to filter[:limit] or :infinity
• :paginate_interval - delay in milliseconds between pages (default: 0)
• :paginate_early_stop_threshold - when a page returns fewer events than this value, stop paginating (default: 100)

Examples

iex> Nostr.Client.fetch(["wss://relay.example.com"], %{kinds: [1]})
{:ok, [%{"id" => "event_id", "kind" => 1, ...}]}

iex> Nostr.Client.fetch(["wss://relay1.com", "wss://relay2.com"], %{authors: ["pubkey"]}, idle_ms: 1000)
{:ok, [%{"id" => "event_id", "pubkey" => "pubkey", ...}]}

@spec publish([relay_uri()], map(), Keyword.t()) ::
  {:ok, publish_result()}
  | {:error, {:min_ok_not_met, publish_result()}}
  | {:error, term()}

Publishes an event to the specified relays and waits for OK acks.

Options:

• :min_ok - minimum number of relays that must acknowledge OK (default: 1)
• :overall_timeout - hard stop timeout in milliseconds (default: 30_000)

@spec stream([relay_uri()], filter(), Keyword.t()) ::
  {:ok, query_ref()} | {:error, term()}

Starts a streaming query to the specified relays using the given filter.

This is a non-blocking call that returns immediately with a query reference. The caller receives messages:

• {:nostr_event, query_ref, event} - when a new event arrives
• {:nostr_eose, query_ref, done?} - when a relay sends EOSE (done? is true if all relays are done)

Options

Same options as fetch/3.

Examples

iex> {:ok, ref} = Nostr.Client.stream(["wss://relay.example.com"], %{kinds: [1]})
iex> receive do
...>   {:nostr_event, ^ref, event} -> event
...>   {:nostr_eose, ^ref, true} -> :done
...> end