@spec list(Req.Request.t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, UnifiApi.Error.t()}

Lists site events.

Options

• :within_hours — return events within the last N hours (server-side, sent as within=N)
• :limit — max number of events to return (sent as _limit=N)
• :start — pagination offset within the result set (sent as _start=N)
• :raw — when true, return the raw response body binary (skips JSON decoding and v1 envelope unwrap). Useful for very long event windows where the decoded meta/data envelope would be memory-heavy.

Examples

# Last 24 hours, up to 1000 events
{:ok, events} = UnifiApi.Network.Events.list(client, "default",
  within_hours: 24, limit: 1000)

# Filter to wireless connection events client-side
events
|> Enum.filter(&(&1["subsystem"] == "wlan"))

@spec stream(Req.Request.t(), String.t(), keyword()) :: Enumerable.t()

Returns a lazy stream that auto-paginates events via _start / _limit.

Error contract

A mid-stream error does not raise by default: the stream halts and yields {:error, %UnifiApi.StreamError{}, last_start} as its final element, so the enumerable is heterogeneous and Enum.map(stream, & &1["key"]) crashes on a transient 500. Match the tail:

items = Enum.to_list(stream)

case List.last(items) do
  {:error, error, cursor} -> {:error, error, cursor}
  _ -> {:ok, items}
end

Pass raise_errors: true to raise UnifiApi.StreamError instead.

Options

• :within_hours — passed through to every page request as within=N.
• :limit — page size (default 200).
• :max_pages — halt after this many successful pages (default: unbounded).
• :max_items — halt once this many events have been yielded; the final page is truncated to fit (default: unbounded).
• :raise_errors — when true, raise UnifiApi.StreamError on a mid-stream error instead of yielding {:error, reason, last_start} as the final element (default: false).

:max_pages, :max_items and :raise_errors are forwarded verbatim to UnifiApi.Client.stream_v1/3 and behave exactly as they do in UnifiApi.Client.stream/3. Any other key raises ArgumentError.

Examples

# Stream every event in the last 24 hours
UnifiApi.Network.Events.stream(authed, "default", within_hours: 24)
|> Enum.to_list()

# Bound the work server-side: at most 100 events, at most 2 requests
UnifiApi.Network.Events.stream(authed, "default", max_items: 100, max_pages: 2)
|> Enum.to_list()

# Stop early — only fetches one page
UnifiApi.Network.Events.stream(authed, "default")
|> Enum.take(50)