@spec error_rate(term()) :: float() | nil

Converts a percentage to a float or returns nil.

@spec event_to_api(Monitorex.Event.t()) :: map()

Converts an Event struct to a safe API map, removing internal fields.

@spec json_error(Plug.Conn.t(), String.t(), integer()) :: Plug.Conn.t()

Sends an error response.

Envelope: {"ok": false, "error": message}

@spec json_ok(Plug.Conn.t(), term(), keyword()) :: Plug.Conn.t()

Sends a success response with the given data.

Envelope: {"ok": true, "data": ...}

@spec pagination_headers(integer(), keyword(), integer()) :: [
  {binary(), binary()},
  ...
]

Builds pagination headers for a result set. Returns a list of header tuples.

@spec parse_filters(map()) :: keyword()

Parses common query parameters into storage options.

Supports:

• limit — max results (default: 50, max: 500)
• offset — pagination offset (default: 0)
• status — numeric HTTP status code filter
• status_class — status class atom (:success, :error, :client_error, :server_error, :redirect)
• host — host filter (for outbound events)
• method — HTTP method filter
• consumer — consumer filter (for inbound events)
• route — route key filter (for inbound events)
• direction — "outbound" or "inbound"
• since — ISO 8601 timestamp (filters events after this time, in epoch microseconds)

@spec set_cors(Plug.Conn.t()) :: Plug.Conn.t()

Sets CORS headers for cross-origin access.