class Chatrix::Api::Users

Contains methods to use user endpoints in the API.

Public Instance Methods

get(user) click to toggle source

Gets information about a specific user.

@param user [String] The user to query (`@user:host.tld`). @return [Hash] The user information. @raise [UserNotFoundError] If the user could not be found.

@example Print a user's display name

puts get_user('@foo:matrix.org')['displayname']
# File lib/chatrix/api/users.rb, line 18
def get(user)
  make_request(:get, "/profile/#{user}").parsed_response
rescue NotFoundError => e
  raise UserNotFoundError.new(user, e.error),
        'The specified user could not be found'
end
get_avatar(user) click to toggle source

Get the URL to a user's avatar (an `mxp://` URL).

@param (see get_user) @return [String] The avatar URL. @raise [AvatarNotFoundError] If the avatar or user could not be found.

# File lib/chatrix/api/users.rb, line 30
def get_avatar(user)
  make_request(:get, "/profile/#{user}/avatar_url")['avatar_url']
rescue NotFoundError => e
  raise AvatarNotFoundError.new(user, e.error),
        'Avatar or user could not be found'
end
get_displayname(user) click to toggle source

Get a user's display name (not username).

@param (see get_user) @raise (see get_user) @return [String] The user's display name.

# File lib/chatrix/api/users.rb, line 56
def get_displayname(user)
  make_request(:get, "/profile/#{user}/displayname")['displayname']
rescue NotFoundError => e
  raise UserNotFoundError.new(user, e.error),
        'The specified user could not be found'
end
get_presence_list(user) click to toggle source

Gets the presence list for a user.

@param user [String] The user whose list to get. @return [Array] A list of presences for this user.

@todo The official documentation on this endpoint is weird, what does

this really do?
# File lib/chatrix/api/users.rb, line 116
def get_presence_list(user)
  make_request(:get, "/presence/list/#{user}").parsed_response
end
get_presence_status(user) click to toggle source

Gets the presence status of a user.

@param user [String] The user to query. @return [Hash] Hash with information about the user's presence,

contains information indicating if they are available and when
they were last active.
# File lib/chatrix/api/users.rb, line 154
def get_presence_status(user)
  make_request(:get, "/presence/#{user}/status").parsed_response
end
set_avatar(user, avatar) click to toggle source

Sets a new avatar for a user.

@param user [String] The user to update. @param avatar [String] The new avatar to set, an `mxc://` URL. @return [Boolean] `true` if the new avatar was set successfully,

otherwise `false`.
# File lib/chatrix/api/users.rb, line 43
def set_avatar(user, avatar)
  make_request(
    :put,
    "/profile/#{user}/avatar_url",
    content: { avatar_url: avatar }
  ).code == 200
end
set_data(user, type, data) click to toggle source

Sets account data for a user.

@param user [String] The user to add the data to. @param type [String] The event type of `account_data` to set. @param data [Hash] The actual data to set. @return [Boolean] `true` if the account data was successfully set,

otherwise `false`.
# File lib/chatrix/api/users.rb, line 87
def set_data(user, type, data)
  make_request(
    :put,
    "/user/#{user}/account_data/#{type}",
    content: data
  ).code == 200
end
set_displayname(user, displayname) click to toggle source

Sets a new display name for a user.

@note Can only be used on the user who possesses the

{Matrix#access_token access_token} currently in use.

@param user [String] The user to modify (`@user:host.tld`). @param displayname [String] The new displayname to set. @return [Boolean] `true` if the new display name was successfully set,

otherwise `false`.
# File lib/chatrix/api/users.rb, line 72
def set_displayname(user, displayname)
  make_request(
    :put,
    "/profile/#{user}/displayname",
    content: { displayname: displayname }
  ).code == 200
end
set_room_data(user, room, type, data) click to toggle source

Sets account data for a user specific to a certain room.

@param (see set_data) @param room [String] The room to add the data in. @return [Boolean] `true` if the account data was successfully set

in the specified room, otherwise `false`.
# File lib/chatrix/api/users.rb, line 101
def set_room_data(user, room, type, data)
  make_request(
    :put,
    "/user/#{user}/rooms/#{room}/account_data/#{type}",
    content: data
  ).code == 200
end
update_presence_list(user, data) click to toggle source

Adds or removes users from a user's presence list.

@param user [String] The user whose list to modify. @param data [Hash{String=>Array<String>}] Contains two arrays,

`invite` and `drop`. Users listed in the `invite` array will be
invited to join the presence list. Users listed in the `drop` array
will be removed from the presence list.
Note that both arrays are not required but at least one must be
present.

@return [Boolean] `true` if the list was successfully updated,

otherwise `false`.

@example Add and remove two users

update_presence_list(
  '@me:home.org',
  {
    invite: ['@friend:home.org'],
    drop: ['@enemy:other.org']
  }
)
# File lib/chatrix/api/users.rb, line 140
def update_presence_list(user, data)
  make_request(
    :post,
    "/presence/list/#{user}",
    content: { presence_diff: data }
  ).code == 200
end
update_presence_status(user, status, message = nil) click to toggle source

Updates the presence status of a user.

@note Only the user for whom the {Matrix#access_token access_token} is

valid for can have their presence updated.

@param user [String] The user to update. @param status [String] The new status to set. Eg. `'online'`

or `'offline'`.

@param message [String,nil] If set,

associates a message with the status.

@return [Boolean] `true` if the presence was updated successfully,

otherwise `false`.
# File lib/chatrix/api/users.rb, line 170
def update_presence_status(user, status, message = nil)
  content = { presenceState: { presence: status } }

  content[:presenceState][:status_msg] = message if message

  make_request(:put, "/presence/#{user}/status", content: content)
    .code == 200
end