ExNtfy.Subscribe.Options (ex_ntfy v0.1.1)

Copy Markdown View Source

Validates subscribe options and builds subscribe URLs — shared infrastructure for one-shot polling (ExNtfy.poll/2, Phase 5) and the Phase 6 streaming subscriptions, which call path/2 with a stream format and to_query/1 without poll=1.

path/2 builds the topic path (single topic, list, or comma-separated string — topics are individually percent-escaped); to_query/1 validates and encodes the options below, raising NimbleOptions.ValidationError on anything unknown.

Options

  • :since - Return cached messages since: a duration or message-ID string (passed through verbatim — the server disambiguates), a non-negative unix timestamp, a DateTime, :all, or :latest (most recent message only).

  • :scheduled (boolean/0) - true includes not-yet-delivered scheduled messages.

  • :id (String.t/0) - Filter: exact message ID.

  • :message (String.t/0) - Filter: exact message body match.

  • :title (String.t/0) - Filter: exact title match.

  • :priority - Filter: a single priority or a list (any match / logical OR) — 1..5 or the same atoms as publishing (:min … :urgent).

  • :tags - Filter: list of tags that must all match (logical AND).

Summary

Types

option()

Any subscribe option from the schema above.

topics()

One or many topic names.

Functions

path(topics, format \\ :json)

Builds the subscribe path for one or many topics and a stream format.

to_query(opts)

Validates subscribe options and encodes them as query parameters, in a stable canonical order. poll=1 is not an option — ExNtfy.poll/2 adds it itself.

topics_segment(topics)

Joins and percent-escapes topics into a single path segment.

Types

option()

@type option() :: {atom(), term()}

Any subscribe option from the schema above.

topics()

@type topics() :: String.t() | [String.t()]

One or many topic names.

Functions

path(topics, format \\ :json)

@spec path(topics(), :json | :sse | :raw | :ws) :: String.t()

Builds the subscribe path for one or many topics and a stream format.

Topics may be a string, a list, or a comma-separated string; each topic is percent-escaped individually (commas stay as separators).

Examples

iex> ExNtfy.Subscribe.Options.path("mytopic")
"/mytopic/json"

iex> ExNtfy.Subscribe.Options.path(["topic1", "topic2"], :sse)
"/topic1,topic2/sse"

to_query(opts)

@spec to_query([option()]) :: keyword(String.t())

Validates subscribe options and encodes them as query parameters, in a stable canonical order. poll=1 is not an option — ExNtfy.poll/2 adds it itself.

Examples

iex> ExNtfy.Subscribe.Options.to_query(since: :latest, scheduled: true)
[since: "latest", scheduled: "1"]

iex> ExNtfy.Subscribe.Options.to_query(priority: [:high, 5], tags: [:warning, "backup"])
[priority: "4,5", tags: "warning,backup"]

topics_segment(topics)

@spec topics_segment(topics()) :: String.t()

Joins and percent-escapes topics into a single path segment.

Examples

iex> ExNtfy.Subscribe.Options.topics_segment(["alerts", "backups"])
"alerts,backups"