Class: Chatrix::Api::Users

Inherits:
ApiComponent show all
Defined in:
lib/chatrix/api/users.rb

Overview

Contains methods to use user endpoints in the API.

Instance Method Summary collapse

Methods inherited from ApiComponent

#initialize, #make_request

Constructor Details

This class inherits a constructor from Chatrix::Api::ApiComponent

Instance Method Details

#get(user) ⇒ Hash

Gets information about a specific user.

Examples:

Print a user's display name

puts get_user('@foo:matrix.org')['displayname']

Parameters:

  • user (String) —

    The user to query (@user:host.tld).

Returns:

  • (Hash) —

    The user information.

Raises:



18
19
20
21
22
23
 
# 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) ⇒ String

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

Returns:

  • (String) —

    The avatar URL.

Raises:



30
31
32
33
34
35
 
# 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) ⇒ String

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

Returns:

  • (String) —

    The user's display name.



56
57
58
59
60
61
 
# 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) ⇒ Array

TODO:

The official documentation on this endpoint is weird, what does this really do?

Gets the presence list for a user.

Parameters:

  • user (String) —

    The user whose list to get.

Returns:

  • (Array) —

    A list of presences for this user.



116
117
118
 
# 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) ⇒ Hash

Gets the presence status of a user.

Parameters:

  • user (String) —

    The user to query.

Returns:

  • (Hash) —

    Hash with information about the user's presence, contains information indicating if they are available and when they were last active.



154
155
156
 
# 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) ⇒ Boolean

Sets a new avatar for a user.

Parameters:

  • user (String) —

    The user to update.

  • avatar (String) —

    The new avatar to set, an mxc:// URL.

Returns:

  • (Boolean) —

    true if the new avatar was set successfully, otherwise false.



43
44
45
46
47
48
49
 
# 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) ⇒ Boolean

Sets account data for a user.

Parameters:

  • user (String) —

    The user to add the data to.

  • type (String) —

    The event type of account_data to set.

  • data (Hash) —

    The actual data to set.

Returns:

  • (Boolean) —

    true if the account data was successfully set, otherwise false.



87
88
89
90
91
92
93
 
# 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) ⇒ Boolean

Note:

Can only be used on the user who possesses the access_token currently in use.

Sets a new display name for a user.

Parameters:

  • user (String) —

    The user to modify (@user:host.tld).

  • displayname (String) —

    The new displayname to set.

Returns:

  • (Boolean) —

    true if the new display name was successfully set, otherwise false.



72
73
74
75
76
77
78
 
# 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) ⇒ Boolean

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

Parameters:

  • room (String) —

    The room to add the data in.

  • user (String) —

    The user to add the data to.

  • type (String) —

    The event type of account_data to set.

  • data (Hash) —

    The actual data to set.

Returns:

  • (Boolean) —

    true if the account data was successfully set in the specified room, otherwise false.



101
102
103
104
105
106
107
 
# 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) ⇒ Boolean

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

Examples:

Add and remove two users

update_presence_list(
  '@me:home.org',
  {
    invite: ['@friend:home.org'],
    drop: ['@enemy:other.org']
  }
)

Parameters:

  • user (String) —

    The user whose list to modify.

  • 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.

Returns:

  • (Boolean) —

    true if the list was successfully updated, otherwise false.



140
141
142
143
144
145
146
 
# 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) ⇒ Boolean

Note:

Only the user for whom the access_token is valid for can have their presence updated.

Updates the presence status of a user.

Parameters:

  • user (String) —

    The user to update.

  • status (String) —

    The new status to set. Eg. 'online' or 'offline'.

  • message (String, nil) (defaults to: nil) —

    If set, associates a message with the status.

Returns:

  • (Boolean) —

    true if the presence was updated successfully, otherwise false.



170
171
172
173
174
175
176
177
 
# 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